@forwardimpact/outpost 3.12.0 → 3.12.1

package/templates/.claude/skills/sync-apple-mail/scripts/parse-emlx.mjs

@@ -3,11 +3,11 @@
  * Parse a macOS Mail .emlx or .partial.emlx file and output the plain text body.
  *
  * The .emlx format is: first line = byte count, then RFC822 message, then Apple
- * plist. This script reads the RFC822 portion, walks MIME parts to find
- * text/plain, and prints it to stdout. If the email is HTML-only, falls back to
- * stripping tags and decoding entities.
+ * plist. This script reads the RFC822 portion. It walks the MIME parts to find
+ * text/plain. It prints that part to stdout. If the email is HTML-only, the
+ * script strips the tags and decodes the entities instead.
  *
- * Also exports `parseEmlx()` and `extractBody()` for use by sync-apple-mail.
+ * It also exports `parseEmlx()` and `extractBody()` for sync-apple-mail.
  */
 
 if (process.argv.includes("-h") || process.argv.includes("--help")) {
@@ -16,7 +16,7 @@ if (process.argv.includes("-h") || process.argv.includes("--help")) {
 Usage: node scripts/parse-emlx.mjs <path-to-emlx-file> [-h|--help]
 
 Parses a macOS Mail .emlx or .partial.emlx file and prints the plain text
-body to stdout. Falls back to stripping HTML tags for HTML-only emails.`);
+body to stdout. For an HTML-only email, it strips the HTML tags instead.`);
   process.exit(0);
 }
 
@@ -127,7 +127,7 @@ function parseHeaders(raw) {
       continue;
     }
 
-    // New header — save previous
+    // New header. Save the previous one.
     pushHeader(headers, currentName, currentValue);
 
     const colonIdx = line.indexOf(":");
@@ -141,7 +141,7 @@ function parseHeaders(raw) {
 }
 
 /**
- * Parse Content-Type header value.
+ * Parse a Content-Type header value.
  * @param {string} value - e.g. 'text/plain; charset="utf-8"; boundary="abc"'
  * @returns {{ type: string, params: Record<string, string> }}
  */
@@ -217,7 +217,7 @@ function decodePayload(data, encoding) {
 }
 
 /**
- * Decode text from a buffer using the given charset.
+ * Decode text from a buffer with the given charset.
  * @param {Buffer} data
  * @param {string} [charset]
  * @returns {string}
@@ -342,7 +342,7 @@ export function extractBody(raw) {
  */
 export function parseEmlx(filePath) {
   const data = readFileSync(filePath);
-  // First line is the byte count
+  // The first line is the byte count
   const newline = data.indexOf(0x0a);
   const byteCount = parseInt(data.subarray(0, newline).toString("ascii"), 10);
   const raw = data.subarray(newline + 1, newline + 1 + byteCount);

package/templates/.claude/skills/sync-apple-mail/scripts/sync-helpers.mjs

@@ -11,9 +11,10 @@ import { basename, join, resolve, sep } from "node:path";
 import { homedir } from "node:os";
 import { globSync } from "node:fs";
 
-// node:sqlite is loaded lazily via createRequire so this module can be imported
-// in test environments (bun, older node) that lack the built-in. The only call
-// site is openDb below; production runs on Node 22+ where node:sqlite resolves.
+// This module loads node:sqlite lazily through createRequire. Test environments
+// (bun, older node) that lack the built-in can then import this module. The
+// only call site is openDb below. Production runs on Node 22+, where
+// node:sqlite resolves.
 const requireModule = createRequire(import.meta.url);
 
 const HOME = homedir();
@@ -31,13 +32,15 @@ export function findDb() {
     .sort()
     .reverse();
   if (paths.length === 0) {
-    console.error("Error: Apple Mail database not found. Is Mail configured?");
+    console.error(
+      "Error: Apple Mail database not found. Check that Mail is configured.",
+    );
     process.exit(1);
   }
   return paths[0];
 }
 
-/** Open a read-only SQLite connection, retrying once if the database is locked. */
+/** Open a read-only SQLite connection. Retry once if the database is locked. */
 export function openDb(dbPath) {
   const { DatabaseSync } = requireModule("node:sqlite");
   try {
@@ -51,7 +54,7 @@ export function openDb(dbPath) {
   }
 }
 
-/** Execute a SQL query and return all rows, logging errors and returning an empty array on failure. */
+/** Execute a SQL query and return all rows. Log the error and return an empty array on failure. */
 export function query(db, sql) {
   try {
     return db.prepare(sql).all();
@@ -61,7 +64,7 @@ export function query(db, sql) {
   }
 }
 
-/** Load the last sync timestamp from disk, falling back to daysBack days ago on first run. */
+/** Load the last sync timestamp from disk. Use daysBack days ago on the first run. */
 export function loadLastSync(daysBack = 30) {
   try {
     const iso = readFileSync(STATE_FILE, "utf-8").trim();
@@ -84,7 +87,7 @@ export function saveSyncState(lastRowid = null) {
   }
 }
 
-/** Load the last-seen message ROWID from disk, returning 0 on first run. */
+/** Load the last-seen message ROWID from disk. Return 0 on the first run. */
 export function loadLastRowid() {
   try {
     const val = readFileSync(ROWID_STATE_FILE, "utf-8").trim();
@@ -108,7 +111,7 @@ export function unixToReadable(ts) {
   }
 }
 
-/** Detect whether the messages table uses conversation_id or thread_id for threading. */
+/** Detect whether the messages table uses conversation_id or thread_id as the thread column. */
 export function discoverThreadColumn(db) {
   const rows = query(db, "PRAGMA table_info(messages);");
   const columns = new Set(rows.map((r) => r.name));
@@ -137,7 +140,7 @@ export function findChangedThreads(db, threadCol, sinceTs, lastRowid) {
   );
 }
 
-/** Fetch all messages in a thread ordered by date, including sender and summary metadata. */
+/** Fetch all messages in a thread ordered by date, with sender and summary metadata. */
 export function fetchThreadMessages(db, threadCol, tid) {
   return query(
     db,
@@ -217,13 +220,13 @@ export function fetchAttachments(db, messageIds) {
 }
 
 const FALLBACK_ATTACHMENT_NAME = "unnamed";
-// biome-ignore lint/suspicious/noControlCharactersInRegex: intentional — stripping ASCII control bytes from attacker-controlled filenames.
+// biome-ignore lint/suspicious/noControlCharactersInRegex: intentional. It strips ASCII control bytes from attacker-controlled filenames.
 const CONTROL_CHARS_RE = /[\x00-\x1f\x7f]/g;
 
 /**
  * Coerce an arbitrary `attachments.name` value into a single, non-empty
  * basename safe to join under a per-thread destDir. Strips path separators
- * (POSIX and win32), strips ASCII control bytes, then takes the last
+ * (POSIX and win32). Strips ASCII control bytes. Then takes the last
  * non-empty/non-dot segment. Returns `"unnamed"` for any input that
  * collapses to empty, `.`, or `..`. Never throws.
  */
@@ -341,7 +344,7 @@ function copySingleAttachment(
   }
 }
 
-/** Copy all attachments for a thread's messages into the cache directory, deduplicating filenames. `attachmentsDir` defaults to the module-level `ATTACHMENTS_DIR`; tests inject a temp directory. */
+/** Copy all attachments for a thread's messages into the cache directory and deduplicate the filenames. `attachmentsDir` defaults to the module-level `ATTACHMENTS_DIR`. Tests inject a temp directory. */
 export function copyThreadAttachments(
   threadId,
   messages,

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

@@ -3,9 +3,9 @@
  * Sync Apple Mail threads to ~/.cache/fit/outpost/apple_mail/ as markdown.
  *
  * Queries the macOS Mail Envelope Index SQLite database for threads with new
- * messages since the last sync. Writes one markdown file per thread containing
- * sender, recipients, date, body text (parsed from .emlx files), and attachment
- * links. Attachments are copied into a per-thread subdirectory.
+ * messages since the last sync. Writes one markdown file per thread. Each file
+ * holds the sender, recipients, date, body text (parsed from .emlx files), and
+ * attachment links. Copies the attachments into a per-thread subdirectory.
  *
  * Requires macOS with Mail app configured and Full Disk Access granted.
  */

package/templates/.claude/skills/sync-teams/SKILL.md

@@ -1,21 +1,21 @@
 ---
 name: sync-teams
-description: Sync recent Microsoft Teams chat messages into ~/.cache/fit/outpost/teams_chat/ as markdown files by reading the Teams IndexedDB cache from disk. Use on a schedule or when the user asks to sync their Teams chats. Requires macOS with the Teams desktop app installed.
+description: Sync recent Microsoft Teams chat messages into ~/.cache/fit/outpost/teams_chat/ as markdown files. The skill reads the Teams IndexedDB cache from disk. Use on a schedule or when the user asks to sync their Teams chats. Requires macOS with the Teams desktop app installed.
 compatibility: Requires macOS with Microsoft Teams desktop app (com.microsoft.teams2) installed
 ---
 
 # Sync Teams
 
 Sync recent Microsoft Teams chat messages into
-`~/.cache/fit/outpost/teams_chat/` as markdown files. This is an automated data
-pipeline skill — it ingests chat data that other skills (like
+`~/.cache/fit/outpost/teams_chat/` as markdown files. This is an automated skill
+in the data pipeline. It ingests chat data that other skills (like
 `extract-entities`) consume downstream.
 
-This skill reads the Teams IndexedDB cache directly from disk — no browser
-automation, no API tokens, no network access needed. The Teams desktop app
-(which uses Edge WebView2) stores conversations and messages in a LevelDB-backed
-IndexedDB at a known location. This skill parses those files, deserializes the
-V8-encoded records, and writes markdown.
+This skill reads the Teams IndexedDB cache directly from disk. It needs no
+browser automation, no API tokens, and no network access. The Teams desktop app
+uses Edge WebView2. The app stores conversations and messages in a
+LevelDB-backed IndexedDB at a known location. This skill parses those files,
+deserializes the V8-encoded records, and writes markdown.
 
 ## Trigger
 
@@ -59,7 +59,7 @@ The script:
 1. Reads all LevelDB `.ldb` (SSTable) and `.log` (write-ahead log) files from
    the Teams IndexedDB directory
 2. Decompresses Snappy-compressed blocks and deserializes V8-encoded values
-   using Node's built-in `v8.deserialize()`
+   with Node's built-in `v8.deserialize()`
 3. Extracts conversation records (with member lists, topics, chat type) and
    message records (with sender names, HTML content, timestamps)
 4. Groups messages by conversation, filters by date window, and converts HTML
@@ -69,7 +69,7 @@ The script:
 
 ### Architecture
 
-Three modules, following the same pattern as `sync-apple-mail`:
+Three modules follow the same pattern as `sync-apple-mail`:
 
 | Module                       | Purpose                                                                                                                     |
 | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
@@ -87,17 +87,17 @@ data in LevelDB (the same way Chrome does). The key databases are:
 - **replychain-manager** — stores actual messages: sender display name, HTML
   content, timestamps, reactions, edit status
 
-Since LevelDB is an append-only format, files can be read while Teams is
-running. Newer `.ldb` files supersede older ones for the same records.
+LevelDB is an append-only format. So you can read the files while Teams runs.
+Newer `.ldb` files supersede older ones for the same records.
 
 ### Name Resolution
 
-Teams conversation records don't store human-readable member names — only orgid
-identifiers. Display names are resolved from:
+Teams conversation records do not store human-readable member names. They store
+orgid identifiers only. Resolve display names from:
 
 1. **Conversation topic** (for named group chats)
-2. **Message sender names** (`imDisplayName` field) — for 1:1 chats, the chat is
-   named after the other participant(s)
+2. **Message sender names** (`imDisplayName` field) — a 1:1 chat takes the name
+   of the other participant(s)
 
 ## Output Format
 
@@ -144,14 +144,13 @@ Key conventions:
 
 - Messages in **chronological order** (oldest first)
 - **Normalize names** from Teams format ("Last, First") to "First Last"
-- **Platform** line distinguishes Teams from email in downstream processing
-- **Plain text only** — HTML is stripped, mentions are preserved as plain text
-- **Attachments are not extracted** — files/images on a message are dropped from
-  the markdown. They are hosted on SharePoint/OneDrive, not in the local cache.
-  However, the user has **often manually downloaded** them, so an attachment
-  usually exists under `~/Downloads/` with the **same file name** shown in
-  Teams. When a message references an attachment and you need its contents, look
-  there first.
+- The **Platform** line distinguishes Teams from email downstream
+- **Plain text only** — the script strips HTML. Mentions stay as plain text
+- **The script does not extract attachments** — it drops files and images from
+  the markdown. SharePoint or OneDrive hosts them. The local cache does not. But
+  the user **often downloads them manually**, so an attachment usually exists
+  under `~/Downloads/` with the **same file name** Teams shows. When a message
+  references an attachment and you need its contents, look there first.
 - Skip system messages (calls, member adds/removes, topic changes)
 
 ## Error Handling
@@ -161,29 +160,30 @@ Key conventions:
 - LevelDB file parse error → skip that file, continue with others
 - V8 deserialization failure → skip that record, continue
 - Snappy decompression failure → skip that block, continue
-- Empty chat (no messages in window) → skip, don't write a file
+- Empty chat (no messages in window) → skip, do not write a file
 - Always update sync state, even on partial success
 
 ## Constraints
 
-- **Read-only.** Never writes to the Teams IndexedDB or sends messages.
-- **Cache-dependent.** Only conversations cached locally by Teams are available.
-  This covers recently viewed chats, not full history.
-- **Both 1:1 and group chats** are synced (channels are excluded).
-- **No message limit per chat** — all cached messages within the `--days` window
-  are included.
+- **Read-only.** The script never writes to the Teams IndexedDB or sends
+  messages.
+- **Cache-dependent.** Only the conversations Teams caches locally are
+  available. This covers recently viewed chats. It does not cover full history.
+- **Both 1:1 and group chats.** The script syncs both and excludes channels.
+- **No message limit per chat** — the output holds every cached message within
+  the `--days` window.
 
 ## Limitations
 
-- The IndexedDB is a **cache, not an archive**. Only conversations the user has
-  recently opened in Teams will have cached message data. Older conversations
-  that haven't been opened may have conversation metadata but no messages.
-- Clearing the Teams cache (a common troubleshooting step) will temporarily
-  remove all local data until Teams rebuilds it from the server.
-- Some V8-serialized records (~17% in testing) use formats that
-  `v8.deserialize()` cannot decode. These are silently skipped — they are
-  typically IndexedDB metadata, not conversation or message records.
-- **Attachments (files/images) are never synced into the markdown** — only the
-  message text is captured. The binaries live on SharePoint/OneDrive, but the
-  user frequently downloads them, so the same-named file is usually already in
-  `~/Downloads/`. Check there before trying to fetch from SharePoint.
+- The IndexedDB is a **cache**. It is not an archive. Only the conversations the
+  user opened recently in Teams have cached message data. An older conversation
+  the user never opened may have conversation metadata but no messages.
+- If you clear the Teams cache (a common troubleshooting step), all local data
+  goes away until Teams rebuilds it from the server.
+- Some V8-serialized records (~17% in tests) use formats that `v8.deserialize()`
+  cannot decode. The script skips them silently. They are typically IndexedDB
+  metadata. They are not conversation or message records.
+- **The script never syncs attachments (files/images) into the markdown** — it
+  captures only the message text. The binaries live on SharePoint/OneDrive. But
+  the user downloads them often, so the same-named file is usually already in
+  `~/Downloads/`. Check there before you fetch from SharePoint.

package/templates/.claude/skills/sync-teams/scripts/idb-reader.mjs

@@ -4,7 +4,7 @@
  *
  * Chromium stores IndexedDB data in LevelDB with a specific key encoding
  * (database ID, object store ID) and V8-serialized values wrapped in a Blink
- * envelope. This module handles the key parsing and value deserialization.
+ * envelope. This module parses the keys and deserializes the values.
  *
  * Exports: readIndexedDb(dir) → { conversations: Map, messages: Map }
  */
@@ -32,18 +32,18 @@ function readIdbVarint(buf, offset) {
 }
 
 // Highest V8 serialization wire-format version Node's bundled v8.deserialize
-// accepts. Newer Teams/WebView2 builds write version 16, which Node rejects
-// outright even though the payload itself is wire-compatible. We patch the
-// version byte down to this value before deserializing. Bump if Node's V8
-// starts emitting/accepting a higher version natively.
+// accepts. Newer Teams/WebView2 builds write version 16. Node rejects it
+// outright, even though the payload itself is wire-compatible. We patch the
+// version byte down to this value before we deserialize. Bump this value when
+// Node's V8 emits or accepts a higher version natively.
 const V8_MAX_SUPPORTED_VERSION = 15;
 
 // Plausible V8 top-level value tags that immediately follow the
-// [0xFF <version>] header. Used to locate the real V8 payload start inside the
-// Blink envelope without relying on a fixed byte offset (newer envelopes carry
-// a 0xFE trailer that shifts the payload further in). We only ever ACT on a
-// candidate by attempting a deserialize, which validates it — so a stray match
-// just gets skipped.
+// [0xFF <version>] header. The reader uses them to locate where the real V8
+// payload starts inside the Blink envelope. It does not depend on a fixed byte
+// offset (newer envelopes carry a 0xFE trailer that shifts the payload further
+// in). We only ever ACT on a candidate when we try to deserialize it. That
+// call validates the candidate, so the code skips a stray match.
 const V8_TOP_LEVEL_TAGS = new Set([
   0x6f, // 'o' begin JS object
   0x22, // '"' one-byte string
@@ -62,16 +62,17 @@ const V8_TOP_LEVEL_TAGS = new Set([
   0x30, // '0' null
 ]);
 
-// Only the Blink envelope precedes the V8 payload, and it is always small.
-// Scanning a generous prefix keeps non-message records (which never decode)
-// cheap while comfortably covering every real envelope/trailer layout.
+// Only the Blink envelope precedes the V8 payload. The envelope is always
+// small. A scan over a generous prefix keeps non-message records (which never
+// decode) cheap. It also covers every real envelope/trailer layout comfortably.
 const V8_START_SCAN_LIMIT = 256;
 
 /**
- * Deserialize the V8 payload starting at `off`. Tries the bytes as-is first,
- * then — for records whose version byte is newer than Node supports — retries
- * with the version patched down. The wire format is backward-compatible, so a
- * supported version reads the newer payload correctly.
+ * Deserialize the V8 payload that starts at `off`. Tries the bytes as-is
+ * first. For a record whose version byte is newer than Node supports, it then
+ * retries with the version patched down. The wire format is
+ * backward-compatible, so a supported version reads the newer payload
+ * correctly.
  */
 function deserializeAt(rawValue, off) {
   try {
@@ -99,9 +100,9 @@ function deserializeAt(rawValue, off) {
  * Try to deserialize a Chromium IndexedDB value.
  *
  * Values have a Blink envelope (and, in newer WebView2 builds, a 0xFE trailer)
- * before the V8 payload. Locate the payload by scanning for a [0xFF <version>
- * <top-level tag>] header, then decode it — patching the version byte down for
- * records written with a V8 wire version newer than Node accepts.
+ * before the V8 payload. Scan for a [0xFF <version> <top-level tag>] header to
+ * locate the payload. Then decode it. For a record written with a V8 wire
+ * version newer than Node accepts, patch the version byte down first.
  */
 function tryDeserialize(rawValue) {
   if (!rawValue || rawValue.length < 4) return null;
@@ -141,7 +142,7 @@ function _parseKeyPrefix(key) {
  */
 export function readIndexedDb(dir) {
   // Use Maps so later entries (from newer .ldb files) overwrite older ones.
-  // LevelDB reads files in ascending order — newer compactions have higher
+  // LevelDB reads files in ascending order. Newer compactions have higher
   // numbers, so the last write for a given key is the most current.
   const convMap = new Map();
   const msgMap = new Map();

package/templates/.claude/skills/sync-teams/scripts/leveldb-reader.mjs

@@ -2,8 +2,8 @@
 /**
  * Read LevelDB SSTable (.ldb) and write-ahead log (.log) files.
  *
- * Parses the binary SSTable format directly — no LevelDB library needed.
- * Handles Snappy-compressed blocks via snappyjs (pure JS, zero native deps).
+ * Parses the binary SSTable format directly. It needs no LevelDB library.
+ * Handles Snappy-compressed blocks with snappyjs (pure JS, zero native deps).
  *
  * Exports a single generator function: readAllEntries(directory)
  */
@@ -146,7 +146,7 @@ const LOG_BLOCK_SIZE = 32768;
 const LOG_HEADER_SIZE = 7; // checksum(4) + length(2) + type(1)
 
 /**
- * Parse records from a single WAL block, yielding { payload, type } for each.
+ * Parse records from a single WAL block. Yield { payload, type } for each one.
  */
 function* parseLogBlock(fileData, blockStart, blockEnd) {
   let offset = blockStart;
@@ -244,7 +244,7 @@ function* parseWriteBatchEntries(batchData) {
 
       yield { key, value };
     } else if (tag === 0) {
-      // Delete — skip the key
+      // Delete. Skip the key.
       const keyLen = readVarint(batchData, pos);
       pos += keyLen.bytesRead;
       pos += keyLen.value;

package/templates/.claude/skills/sync-teams/scripts/sync.mjs

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 /**
  * Sync Microsoft Teams chat messages to ~/.cache/fit/outpost/teams_chat/ as
- * markdown files. Reads the Teams IndexedDB cache (LevelDB on disk) directly —
- * no browser automation, no API tokens, no network access needed.
+ * markdown files. Reads the Teams IndexedDB cache (LevelDB on disk) directly.
+ * It needs no browser automation, no API tokens, and no network access.
  *
  * Requires macOS with the Microsoft Teams desktop app installed.
  * Requires snappyjs: npm install snappyjs
@@ -272,7 +272,7 @@ function loadUserIdentity() {
     const nameMatch = identityMd.match(/\*\*Name:\*\*\s*(.+)/);
     if (nameMatch) return nameMatch[1].trim();
   } catch {
-    // identity cache not found or not readable — run the identify-user skill
+    // identity cache not found or not readable. Run the identify-user skill
   }
   return "";
 }
@@ -326,7 +326,7 @@ function main() {
 
   if (!existsSync(TEAMS_IDB_DIR)) {
     console.error(
-      "Error: Teams IndexedDB not found. Is the Teams desktop app installed?",
+      "Error: Teams IndexedDB not found. Check that the Teams desktop app is installed.",
     );
     console.error(`Expected: ${TEAMS_IDB_DIR}`);
     process.exit(1);

package/templates/.claude/skills/upstream-instructions/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: upstream-instructions
-description: Track changes made to this installation's instruction files — the root CLAUDE.md, agent profiles, and skills — and record them in a single root CHANGELOG.md so improvements can be contributed back to the upstream monorepo. Use when CLAUDE.md, agents, or skills have been modified, added, or removed locally and those changes should be documented for upstream.
+description: Track changes to this installation's instruction files: the root CLAUDE.md, agent profiles, and skills. Record them in a single root CHANGELOG.md so you can contribute improvements back to the upstream monorepo. Use when someone modified, added, or removed CLAUDE.md, agents, or skills locally and you should document those changes for upstream.
 ---
 
 # Upstream Instructions
 
-Track changes to this installation's **instructions** and record them in one
-root `CHANGELOG.md` so improvements can be contributed back to the upstream
-monorepo. "Instructions" means all three surfaces, treated equally:
+Track changes to this installation's **instructions**. Record them in one root
+`CHANGELOG.md` so you can contribute improvements back to the upstream monorepo.
+"Instructions" means all three surfaces, and they carry equal weight:
 
 - **`CLAUDE.md`** (root) — installation-wide instructions.
 - **`.claude/agents/*.md`** — agent profiles.
@@ -16,9 +16,9 @@ monorepo. "Instructions" means all three surfaces, treated equally:
 ## Trigger
 
 - The user asks to prepare local instruction changes for upstream contribution.
-- The root `CLAUDE.md`, an agent profile, or a skill has been modified, added,
-  or removed.
-- The user wants to document what changed locally before syncing upstream.
+- Someone modified, added, or removed the root `CLAUDE.md`, an agent profile, or
+  a skill.
+- The user wants to document what changed locally before the sync upstream.
 
 ## Prerequisites
 
@@ -31,27 +31,26 @@ monorepo. "Instructions" means all three surfaces, treated equally:
 - `.claude/agents/*.md` — agent profiles.
 - `.claude/skills/*/SKILL.md` and reference files — skills.
 - `CHANGELOG.md` (root) — the existing changelog, for what's already recorded.
-- The changes made in the current working session — the source of truth for what
-  changed, since the KB lives on a synced filesystem and is not
-  version-controlled.
+- The changes you made in the current working session — the source of truth for
+  what changed. The KB lives on a synced filesystem. It has no version control.
 
 ## Outputs
 
-- `CHANGELOG.md` (root) — a **single** reverse-chronological changelog covering
-  all three surfaces. There are no per-skill or per-agent changelogs.
+- `CHANGELOG.md` (root) — a **single** reverse-chronological changelog that
+  covers all three surfaces. There are no per-skill or per-agent changelogs.
 
 <do_confirm_checklist goal="Verify the changelog is upstream-ready">
 
-- [ ] Exactly one root `CHANGELOG.md`; no stray per-skill / per-agent changelogs
-      left behind.
-- [ ] Every entry names its **Scope** (which surface(s) and file(s) it touched).
-- [ ] Each entry has **What**, **Why**, and **Details**.
-- [ ] Descriptions are specific enough for an upstream maintainer to act on (not
-      "updated CLAUDE.md" / "fixed stuff").
-- [ ] New skills/agents include a brief description of their purpose; removed
-      ones explain why.
-- [ ] Dates are the date the change was made, not guessed.
-- [ ] No duplicate entries for the same change.
+- [ ] Keep exactly one root `CHANGELOG.md`. Leave no stray per-skill or
+      per-agent changelog behind.
+- [ ] Name the **Scope** in every entry (the surfaces and files it touched).
+- [ ] Give each entry **What**, **Why**, and **Details**.
+- [ ] Make each description specific enough for an upstream maintainer to act
+      on. Never write "updated CLAUDE.md" or "fixed stuff".
+- [ ] Briefly describe the purpose of each new skill or agent. Explain why you
+      removed each deleted one.
+- [ ] Use the real date of the change. Never guess a date.
+- [ ] Write no duplicate entry for the same change.
 
 </do_confirm_checklist>
 
@@ -65,15 +64,15 @@ head -20 CHANGELOG.md 2>/dev/null   # newest date already recorded, if any
 
 ### 2. Identify changed instructions
 
-Knowledge bases live on a synced filesystem, not in Git, so there is no commit
-history to diff. Identify what changed from the work just done **this session**:
-recall every edit, addition, removal, and rename made to `CLAUDE.md`,
-`.claude/agents/`, and `.claude/skills/` during the current conversation, and
-list them per surface.
+Knowledge bases live on a synced filesystem. They do not live in Git, so there
+is no commit history to diff. Identify what changed from the work you did **this
+session**. Recall every edit, addition, removal, and rename you made to
+`CLAUDE.md`, `.claude/agents/`, and `.claude/skills/` during the current
+conversation. List them per surface.
 
-Use `CHANGELOG.md` only to see what's already recorded so you don't duplicate an
-existing entry. If something was clearly changed but you can't reconstruct what
-or why from the session, flag it as needing review rather than guessing.
+Use `CHANGELOG.md` only to see what it already records. Do not duplicate an
+existing entry. If something clearly changed but you cannot
+reconstruct what or why from the session, flag it for review. Do not guess.
 
 ### 3. Classify each change
 
@@ -90,10 +89,10 @@ or why from the session, flag it as needing review rather than guessing.
 | `removed`  | Instruction file or directory deleted                  |
 | `renamed`  | File or directory renamed                              |
 
-A single change often spans surfaces (e.g. a KB-structure change touching
-`CLAUDE.md`, several agents, and several skills) — record it as **one entry**
-whose Scope lists every surface touched. Re-read the affected files to confirm
-the change landed as intended before describing it.
+A single change often spans surfaces. For example, a KB-structure change touches
+`CLAUDE.md`, several agents, and several skills. Record it as **one entry**
+whose Scope lists every surface it touched. Before you describe the change,
+re-read the affected files and confirm it landed as intended.
 
 ### 4. Describe each change
 
@@ -104,8 +103,8 @@ Every entry must answer:
 3. **Details** — a summary of the actual change (not a full diff).
 
 Good: "Agents now read `Knowledge/Priorities/` at the start of every wake and
-flag anything that threatens a priority — drafts and triage were ignoring
-strategic context."
+flag anything that threatens a priority. Drafts and triage ignored strategic
+context."
 
 Bad: "Updated the agents" / "Fixed stuff" / "Changed line 42".
 
@@ -139,8 +138,8 @@ Worked examples in [references/examples.md](references/examples.md).
 
 ## Notes
 
-- This skill **documents only** — it does not push or merge anything.
-- The single root `CHANGELOG.md` is consumed by the **downstream-instructions**
-  skill in the upstream monorepo.
-- When in doubt about whether a change is upstream-worthy, include it; the
+- This skill **documents only**. It does not push or merge anything.
+- The **downstream-instructions** skill in the upstream monorepo consumes the
+  single root `CHANGELOG.md`.
+- When in doubt about whether a change is upstream-worthy, include it. The
   upstream maintainer decides what to incorporate.

package/templates/.claude/skills/upstream-instructions/references/examples.md

@@ -2,8 +2,8 @@
 
 Reference output for `upstream-instructions` Step 5. There is **one** root
 `CHANGELOG.md` with reverse-chronological entries. Each entry's **Scope** names
-the surface(s) it touched — `CLAUDE.md`, `agent:<name>`, `skill:<name>` — and a
-single entry may span several.
+the surfaces it touched: `CLAUDE.md`, `agent:<name>`, `skill:<name>`. A single
+entry may span several surfaces.
 
 ## Cross-surface change (one change, many files)