@forwardimpact/outpost 3.11.0 → 3.12.1

package/templates/.claude/skills/extract-entities/references/templates-priorities.md

@@ -1,7 +1,7 @@
 # Priority Templates
 
-Priorities are **never auto-created** by `extract-entities`. They are set
-deliberately by the user. This template is for manual creation only —
+`extract-entities` **never auto-creates** Priorities. The user sets them
+deliberately. Use this template only for a note you write by hand.
 `extract-entities` and `anarlog-process` only **link to** and **update progress
 on** existing notes.
 

package/templates/.claude/skills/extract-entities/scripts/state.mjs

@@ -2,12 +2,13 @@
 /**
  * Manage graph_processed state for entity extraction.
  *
- * Tracks which source files (synced emails and calendar events) have already
- * been processed by the extract-entities skill. The `check` command lists files
- * that are new or changed since their last recorded hash; `update` marks files
- * as processed by storing their current SHA-256 hash.
+ * The script tracks which source files the extract-entities skill already
+ * processed. Those files are synced emails and calendar events. The `check`
+ * command lists files that are new or changed since their last recorded hash.
+ * The `update` command marks files as processed. It stores the current
+ * SHA-256 hash of each file.
  *
- * State is persisted as a TSV file at
+ * The script keeps the state in a TSV file at
  * ~/.cache/fit/outpost/state/graph_processed (path<TAB>hash).
  */
 
@@ -43,7 +44,7 @@ const SOURCE_DIRS = [
   join(HOME, ".cache/fit/outpost/teams_chat"),
 ];
 
-/** Compute SHA-256 hash of a file. */
+/** Compute the SHA-256 hash of a file. */
 function fileHash(filePath) {
   const data = readFileSync(filePath);
   return createHash("sha256").update(data).digest("hex");
@@ -74,7 +75,7 @@ function saveState(state) {
   writeFileSync(STATE_FILE, text);
 }
 
-/** Find source files that are new or have changed since last processing. */
+/** Find source files that are new or changed since the last run. */
 function check() {
   const state = loadState();
   const newFiles = [];
@@ -97,7 +98,7 @@ function check() {
   return newFiles.length;
 }
 
-/** Mark files as processed by updating their hashes in state. */
+/** Mark files as processed. Update their hashes in the state file. */
 function update(filePaths) {
   const state = loadState();
   for (const fp of filePaths) {

package/templates/.claude/skills/meeting-prep/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: meeting-prep
-description: Prepare for meetings by gathering context from the knowledge base and calendar. Use when the user asks to prep for a meeting or wants a briefing on upcoming meetings. Creates personalized briefings with attendee history, open items, and suggested talking points.
+description: Prepare for meetings. Gather context from the knowledge base and calendar. Use when the user asks to prep for a meeting or wants a briefing on upcoming meetings. Creates personalized briefings with attendee history, open items, and suggested talking points.
 ---
 
 # Meeting Prep
 
-Help the user prepare for meetings by gathering context from the knowledge base
-and calendar. Creates personalized briefing documents with attendee history,
-open items, and suggested talking points.
+Help the user prepare for meetings. Gather context from the knowledge base and
+calendar. Create personalized briefing documents with attendee history, open
+items, and suggested talking points.
 
 ## Trigger
 
@@ -17,7 +17,7 @@ meetings.
 ## Prerequisites
 
 - Calendar data synced in `~/.cache/fit/outpost/apple_calendar/`
-- Knowledge base populated (from `extract-entities` skill)
+- A populated knowledge base (from the `extract-entities` skill)
 
 ## Inputs
 
@@ -25,11 +25,11 @@ meetings.
 - `Knowledge/People/*.md` — attendee context
 - `Knowledge/Organizations/*.md` — company context
 - `Knowledge/Projects/*.md` — project context
-- `Knowledge/Priorities/*.md` — active priorities and strategic context for
-  framing
+- `Knowledge/Priorities/*.md` — active priorities and strategic context to
+  frame the brief
 - `Knowledge/Candidates/*/brief.md` — candidate context (for interview meetings)
-- `Knowledge/Roles/*.md` — role/requisition context (for interview meetings);
-  check the `**Status:**` field to distinguish active from historical reqs
+- `Knowledge/Roles/*.md` — role/requisition context (for interview meetings).
+  Check the `**Status:**` field to distinguish active from historical reqs
 
 ## Outputs
 
@@ -39,7 +39,7 @@ meetings.
 
 ## Critical: Always Look Up Context First
 
-**BEFORE creating any meeting brief, you MUST look up the attendees in the
+**BEFORE you create any meeting brief, you MUST look up the attendees in the
 knowledge base.**
 
 When the user asks to prep for a meeting:
@@ -48,23 +48,23 @@ When the user asks to prep for a meeting:
 2. **SEARCH** — Look up each attendee: `rg -l "Attendee Name" Knowledge/`
 3. **READ** — Read their notes: `cat "Knowledge/People/Attendee Name.md"`
 4. **UNDERSTAND** — Extract role, organization, history, open items
-5. **THEN BRIEF** — Create the meeting brief using this context
+5. **THEN BRIEF** — Create the meeting brief with this context
 
 ## Key Principles
 
-**Ask, don't guess:**
+**Ask. Do not guess:**
 
 - If unclear which meeting, ASK
 - If multiple upcoming meetings, offer choices
 - **WRONG:** "Here's a generic meeting prep template"
 - **RIGHT:** "I see meetings with Sarah (2pm) and John (4pm). Which one?"
 
-**Be thorough, not generic:**
+**Be thorough. Do not be generic:**
 
-- Include specific history, open items, and context from knowledge base
+- Include specific history, open items, and context from the knowledge base
 - Reference actual past interactions and commitments
 
-## Processing Flow
+## Process Flow
 
 ### Step 1: Identify the Meeting
 
@@ -82,7 +82,7 @@ If "prep me for my next meeting":
 
 - Query upcoming events with `--upcoming 2h`
 - Find the next meeting with external attendees
-- Confirm with user if unclear
+- Confirm with the user if unclear
 
 ### Step 2: Parse Calendar Event
 
@@ -102,9 +102,9 @@ rg -l "attendee_name" Knowledge/Projects/
 
 Extract: role/title, company, key facts, previous interactions, open items.
 
-Also check `Knowledge/Priorities/` for context relevant
-to the meeting topic — e.g. if the meeting is about hiring, surface the relevant
-hiring Priority's status and progress.
+Also check `Knowledge/Priorities/` for context relevant to the meeting topic.
+For example, if the meeting is about hiring, surface the relevant hiring
+Priority's status and progress.
 
 ### Step 4: Create Meeting Brief
 
@@ -134,19 +134,20 @@ Suggested Talking Points
 **Guidelines:**
 
 - Use `[[Name]]` wiki-link syntax for cross-references
-- Keep "About" section to 2-3 sentences max
+- Keep the "About" section to 2-3 sentences max
 - History: reverse chronological, 3-5 most relevant items
-- Talking points: concrete, not generic
+- Talking points: concrete. Avoid generic suggestions
 - If no notes exist for a person, mention that and offer to create one
 
 ### Interview Meeting Context
 
-When preparing for interview meetings (title contains "Interview", "Screening",
-"Decomposition", "Panel", or a candidate name from `Knowledge/Candidates/`):
+When you prepare for interview meetings (title contains "Interview",
+"Screening", "Decomposition", "Panel", or a candidate name from
+`Knowledge/Candidates/`):
 
 1. **Read the candidate brief:** `Knowledge/Candidates/{Name}/brief.md`
 2. **Read the Role file:** Look up the `Req` field and read the corresponding
-   `Knowledge/Roles/*.md` file; check the `**Status:**` field for context.
+   `Knowledge/Roles/*.md` file. Check the `**Status:**` field for context.
 3. **Include in the briefing:**
    - Candidate's current status, skills, and screening recommendation
    - Role context: hiring manager, domain lead, remaining positions

package/templates/.claude/skills/organize-files/SKILL.md

@@ -1,15 +1,15 @@
 ---
 name: organize-files
-description: Organize, tidy up, and find files in ~/Desktop/ and ~/Downloads/. Use when the user asks to find, organize, clean up, or tidy files on their Mac. Always previews changes before acting and never deletes without explicit confirmation. Extracts entities from document files using the extract-entities skill.
+description: Organize, tidy up, and find files in ~/Desktop/ and ~/Downloads/. Use when the user asks to find, organize, clean up, or tidy files on their Mac. Always previews changes before it acts. Never deletes without explicit confirmation. Extracts entities from document files with the extract-entities skill.
 compatibility: Requires macOS filesystem access
 ---
 
 # Organize Files
 
 Organize, tidy up, and find files in `~/Desktop/` and `~/Downloads/`. Always
-previews changes before acting and never deletes without explicit confirmation.
+preview changes before you act. Never delete without explicit confirmation.
 
-After organizing, extract entities from document files by invoking the
+After you organize, extract entities from document files. Invoke the
 **`extract-entities`** skill.
 
 ## Trigger
@@ -29,7 +29,7 @@ Run when the user asks to find, organize, clean up, or tidy files on their Mac.
 
 - Organized files moved to logical subdirectories within `~/Desktop/` and
   `~/Downloads/`
-- Entity extraction triggered on document files via the **`extract-entities`**
+- Entity extraction triggered on document files with the **`extract-entities`**
   skill
 - Summary of actions taken
 
@@ -42,22 +42,23 @@ Run when the user asks to find, organize, clean up, or tidy files on their Mac.
 2. **Organize files** — Move files into logical subfolders
 3. **Tidy up** — Clean up cluttered `~/Desktop/` and `~/Downloads/`
 4. **Create structure** — Set up folder hierarchies
-5. **Extract entities** — After organizing, invoke the **`extract-entities`**
-   skill on document files to populate the knowledge graph
+5. **Extract entities** — After you organize, invoke the
+   **`extract-entities`** skill on document files to populate the knowledge
+   graph
 
 ## Key Principles
 
-**Always preview before acting:**
+**Always preview before you act:**
 
-- Show what files will be affected BEFORE moving/deleting
+- Show which files change BEFORE you move or delete them
 - List proposed changes and ask for confirmation
 
 **Be conservative with destructive operations:**
 
 - Never delete without explicit confirmation
-- Prefer moving to a "to-review" folder over deleting
+- Move to a "to-review" folder rather than delete
 
-## Summarizing Contents
+## Summarize the Contents
 
 Get an overview of both directories:
 
@@ -65,7 +66,7 @@ Get an overview of both directories:
 node scripts/summarize.mjs
 ```
 
-## Finding Files
+## Find Files
 
 ```bash
 find ~/Downloads -maxdepth 1 -name "*.pdf" -type f
@@ -76,7 +77,7 @@ find ~/Downloads -maxdepth 1 -type f -mtime +30    # older than 30 days
 find ~/Desktop -maxdepth 1 \( -name "Screenshot*" -o -name "Screen Shot*" \)
 ```
 
-## Organizing by File Type
+## Organize by File Type
 
 Organize a directory into type-based subdirectories (Documents, Images,
 Archives, Installers, Screenshots):
@@ -86,13 +87,13 @@ node scripts/organize-by-type.mjs ~/Downloads
 node scripts/organize-by-type.mjs ~/Desktop
 ```
 
-The script creates subdirectories and moves matching files. It does NOT delete
-anything.
+The script creates subdirectories and moves the files that match. It does NOT
+delete anything.
 
 ## Entity Extraction
 
-After organizing files, identify document files that may contain entity
-information (people, organizations, projects, topics) and invoke the
+After you organize the files, identify document files that may contain entity
+information (people, organizations, projects, topics). Then invoke the
 **`extract-entities`** skill to process them.
 
 ### Which files to send for extraction
@@ -103,8 +104,8 @@ information (people, organizations, projects, topics) and invoke the
 
 ### How to invoke
 
-After organizing, collect the paths of document files and invoke the
-**`extract-entities`** skill, passing the file paths as ad-hoc file inputs.
+After you organize, collect the paths of the document files. Then invoke the
+**`extract-entities`** skill and pass the file paths as ad-hoc file inputs.
 
 ## Output Format
 
@@ -141,10 +142,11 @@ Entity extraction: invoked extract-entities on 12 document files
 
 ## Safety Rules
 
-1. **Never delete without permission** — "cleanup" means organize, not delete
+1. **Never delete without permission** — "cleanup" means organize. It does not
+   mean delete
 2. **Don't touch system folders** — /System, /Library, /Applications
-3. **Don't touch hidden files** — files starting with `.` unless asked
+3. **Don't touch hidden files** — files that start with `.` unless asked
 4. **Limit scope** — only operate on `~/Desktop/` and `~/Downloads/`
-5. **Limit depth** — use `-maxdepth 1` unless user wants recursive
-6. **Show before doing** — always preview first
+5. **Limit depth** — use `-maxdepth 1` unless the user wants recursive
+6. **Show before you act** — always preview first
 7. **Quote paths** — handle spaces: `"$HOME/My Documents"`

package/templates/.claude/skills/organize-files/scripts/organize-by-type.mjs

@@ -2,10 +2,11 @@
 /**
  * Organize files in a directory by type into subdirectories.
  *
- * Scans the top level of the given directory and moves files into category
- * subdirectories: Screenshots, Documents, Images, Archives, and Installers.
- * Categories are determined by file extension and name prefix. Files that do
- * not match any category are left in place. Does NOT delete anything.
+ * The script scans the top level of the given directory. It moves files into
+ * category subdirectories: Screenshots, Documents, Images, Archives, and
+ * Installers. The file extension and the name prefix set the category. The
+ * script leaves a file in place if it matches no category. It does NOT delete
+ * anything.
  */
 
 import {

package/templates/.claude/skills/organize-files/scripts/summarize.mjs

@@ -2,10 +2,10 @@
 /**
  * Summarize the contents of ~/Desktop/ and ~/Downloads/.
  *
- * Counts top-level files in both directories by type (Screenshots, PDFs,
- * Images, Documents, Archives, Installers, Other) and prints a human-readable
- * table for each. Used by the organize-files skill to preview directory
- * contents before organizing.
+ * The script counts top-level files in both directories by type
+ * (Screenshots, PDFs, Images, Documents, Archives, Installers, Other). It
+ * prints a human-readable table for each directory. The organize-files skill
+ * uses this script to preview directory contents before it organizes them.
  */
 
 import { existsSync, readdirSync, statSync } from "node:fs";

package/templates/.claude/skills/person-identify/SKILL.md

@@ -1,14 +1,14 @@
 ---
 name: person-identify
-description: Look up the current user's identity (real name, company, job title, department, email, employee ID, and manager) from the corporate directory via LDAP, authenticated with the existing Kerberos ticket. Use to establish who the knowledge base belongs to, when CLAUDE.md needs the user's identity, or when the user asks "who am I" / for their own directory record. To look up someone *other* than the current user, use the sibling `person-lookup` skill instead.
+description: Look up the current user's identity (real name, company, job title, department, email, employee ID, and manager) from the corporate directory through LDAP. The bind uses the existing Kerberos ticket. Use to establish who the knowledge base belongs to, when CLAUDE.md needs the user's identity, or when the user asks "who am I" / for their own directory record. To look up someone *other* than the current user, use the sibling `person-lookup` skill instead.
 ---
 
 # Person Identify
 
 Resolve the current user's identity from the corporate Active Directory over
 LDAP. This is the canonical way to establish **who the knowledge base belongs
-to** — replacing any static identity file. Results reflect the live directory,
-so a job change or reorg is picked up automatically.
+to**. It replaces any static identity file. Results reflect the live
+directory, so the skill picks up a job change or a reorg automatically.
 
 ## Trigger
 
@@ -20,12 +20,12 @@ so a job change or reorg is picked up automatically.
 
 - A valid **Kerberos ticket** for the user (`klist` shows a principal).
   If absent, get one with `kinit <user>@<REALM>`.
-- Network reachability to a domain controller (on-site or via VPN).
-- `ldapsearch` and `dig` — both ship with macOS; nothing to install.
+- Network access to a domain controller (on-site or through VPN).
+- `ldapsearch` and `dig` — both ship with macOS. You install nothing.
 
-Nothing is hardcoded: the username, realm, base DN, and domain controller are
-all derived at runtime from the ticket and DNS. No password is ever entered —
-the bind uses SASL/GSSAPI against the existing ticket.
+Nothing is hardcoded. The script derives the username, realm, base DN, and
+domain controller at runtime from the ticket and DNS. You never enter a
+password. The bind uses SASL/GSSAPI against the existing ticket.
 
 ## Usage
 
@@ -38,10 +38,11 @@ writes the result to the identity cache (below).
 
 ## Identity cache
 
-The script writes `~/.cache/fit/outpost/state/identity.md` — the **canonical
-identity source** for the rest of the knowledge base, replacing the old static
-`USER.md`. It is auto-generated markdown with `Name`, `Email`, and `Domain`
-fields (plus title, department, company, employee ID, office, and manager):
+The script writes `~/.cache/fit/outpost/state/identity.md`. That file is the
+**canonical identity source** for the rest of the knowledge base. It replaces
+the old static `USER.md`. It is auto-generated markdown with `Name`, `Email`,
+and `Domain` fields (plus title, department, company, employee ID, office, and
+manager):
 
 ```markdown
 - **Name:** Jane Doe
@@ -51,9 +52,9 @@ fields (plus title, department, company, employee ID, office, and manager):
 
 Other skills (e.g. `extract-entities`, `anarlog-process`, `req-track`,
 `req-workday`, `candidate-report`, `sync-teams`) read this file for the user's
-name/email/domain — for self-exclusion and author attribution. They run this
-skill first if the cache is missing or stale. Never hand-edit the cache; re-run
-the skill to refresh it.
+name/email/domain. They use it for self-exclusion and author attribution. They
+run this skill first if the cache is missing or stale. Never hand-edit the
+cache. Run the skill again to refresh it.
 
 ## How it works
 
@@ -76,8 +77,9 @@ ldapsearch -Y GSSAPI -LLL -o ldif-wrap=no -H "ldap://$dc" -b "$base" \
   "(sAMAccountName=$user)" displayName company title department employeeID mail manager
 ```
 
-The `manager` attribute is a DN that may live in another domain, so the script
-resolves it against the **Global Catalog** (port 3268), which is forest-wide.
+The `manager` attribute is a DN that may live in another domain. So the script
+resolves it against the **Global Catalog** (port 3268). The Global Catalog is
+forest-wide.
 
 ## Output
 
@@ -96,9 +98,9 @@ Key attributes returned (names per Active Directory schema):
 
 ## Notes
 
-- To look up **someone else**, use the sibling `person-lookup` skill — it takes
-  free-text input (email or name), searches the Global Catalog forest-wide
-  (`ldap://$dc:3268 -b ''`), handles multiple matches, and does **not** touch
+- To look up **someone else**, use the sibling `person-lookup` skill. It takes
+  free-text input (email or name). It searches the Global Catalog forest-wide
+  (`ldap://$dc:3268 -b ''`). It handles multiple matches. It does **not** touch
   the identity cache.
-- Not Active Directory? The same `ldapsearch -Y GSSAPI` shape works against any
-  Kerberos-backed LDAP directory; only the attribute names differ.
+- Active Directory is not required. The same `ldapsearch -Y GSSAPI` shape works
+  against any Kerberos-backed LDAP directory. Only the attribute names differ.

package/templates/.claude/skills/person-identify/scripts/identify.sh

@@ -1,18 +1,18 @@
 #!/usr/bin/env bash
-# Identify the current user from the corporate directory (Active Directory over LDAP)
-# and cache the result at ~/.cache/fit/outpost/state/identity.md for other skills.
+# Identify the current user from the corporate directory (Active Directory over LDAP).
+# Cache the result at ~/.cache/fit/outpost/state/identity.md for other skills.
 #
-# Generic by design: nothing is hardcoded. The user, realm, and base DN are all
-# derived from the existing Kerberos ticket, and the domain controller is found
-# via DNS SRV records. Works for any AD domain, on or off VPN, as long as a
-# Kerberos ticket exists and a DC is reachable.
+# The script is generic. Nothing is hardcoded. It derives the user, the realm,
+# and the base DN from the existing Kerberos ticket. It finds the domain
+# controller with DNS SRV records. It works for any AD domain, on or off VPN.
+# It needs a Kerberos ticket and a reachable DC.
 #
-# Auth uses SASL/GSSAPI against the existing ticket — no password is ever entered.
+# Auth uses SASL/GSSAPI against the existing ticket. You never enter a password.
 set -u
 
 CACHE="$HOME/.cache/fit/outpost/state/identity.md"
 
-# 1. Who are we? Take the principal from the Kerberos ticket: USER@REALM.EXAMPLE.COM
+# 1. Take the user principal from the Kerberos ticket: USER@REALM.EXAMPLE.COM
 princ=$(klist 2>/dev/null | sed -n 's/.*[Pp]rincipal: *//p' | head -1)
 if [ -z "$princ" ]; then
   echo "No Kerberos ticket found. Get one first, e.g.:  kinit <user>@<REALM>" >&2
@@ -25,11 +25,11 @@ realm=${princ#*@}
 base=$(printf '%s' "$realm" | awk -F. '{for(i=1;i<=NF;i++) printf "%sDC=%s",(i>1?",":""),$i}')
 dom=$(printf '%s' "$realm" | tr '[:upper:]' '[:lower:]')
 
-# 3. Find a reachable domain controller via DNS SRV (msdcs first, then plain ldap)
+# 3. Find a reachable domain controller with DNS SRV (msdcs first, then plain ldap)
 dc=$(dig +short SRV "_ldap._tcp.dc._msdcs.$dom" | awk 'NR==1{print $4}' | sed 's/\.$//')
 [ -z "$dc" ] && dc=$(dig +short SRV "_ldap._tcp.$dom" | awk 'NR==1{print $4}' | sed 's/\.$//')
 if [ -z "$dc" ]; then
-  echo "Could not find a domain controller for $dom via DNS SRV." >&2
+  echo "Could not find a domain controller for $dom with DNS SRV." >&2
   exit 1
 fi
 
@@ -49,13 +49,13 @@ company=$(field company); title=$(field title); dept=$(field department)
 empid=$(field employeeID); mail=$(field mail)
 office=$(field physicalDeliveryOfficeName)
 
-# Real name from given+surname, falling back to displayName. Domain from the email.
+# Real name from given+surname. Fall back to displayName. Domain from the email.
 name="$gn $sn"; name=$(printf '%s' "$name" | sed 's/^ *//;s/ *$//')
 [ -z "$name" ] && name="$disp"
 domain=$(printf '%s' "$mail" | sed 's/.*@//' | tr '[:upper:]' '[:lower:]')
 
-# 5. Resolve the manager DN to a name, if present. Manager may live in another
-#    domain, so query the Global Catalog (port 3268), which is forest-wide.
+# 5. Resolve the manager DN to a name, if present. The manager may live in
+#    another domain. Query the Global Catalog (port 3268). It is forest-wide.
 mgr=$(field manager)
 mgr_name=""
 if [ -n "$mgr" ]; then
@@ -63,14 +63,14 @@ if [ -n "$mgr" ]; then
     displayName 2>/dev/null | sed -n 's/^displayName: //p' | head -1)
 fi
 
-# 6. Write the cache. Same Name/Email/Domain shape other skills already parse,
-#    plus extra fields. Auto-generated — never hand-edited.
+# 6. Write the cache. It keeps the Name/Email/Domain shape other skills already
+#    parse, plus extra fields. The script generates it. Never edit it by hand.
 mkdir -p "$(dirname "$CACHE")"
 {
   echo "# User Identity"
   echo
-  echo "Auto-generated by the \`person-identify\` skill from the corporate directory."
-  echo "Do not edit by hand — re-run the skill to refresh."
+  echo "The \`person-identify\` skill generates this file from the corporate directory."
+  echo "Do not edit it by hand. Run the skill again to refresh it."
   echo
   echo "- **Name:** $name"
   echo "- **Email:** $mail"

package/templates/.claude/skills/person-lookup/SKILL.md

@@ -1,37 +1,37 @@
 ---
 name: person-lookup
-description: Look up ANY person in the corporate directory from free-text input (an email address, or a first / last / full name) and return their record — real name, title, department, company, email, employee ID, office, and manager. Searches the Global Catalog forest-wide via LDAP, authenticated with the existing Kerberos ticket. Use when the user asks "who is X", needs someone's title / department / manager / email, or wants to disambiguate a name. For the *current* user's own identity, use the sibling `person-identify` skill instead.
+description: Look up ANY person in the corporate directory from free-text input (an email address, or a first / last / full name) and return their record: real name, title, department, company, email, employee ID, office, and manager. Searches the Global Catalog forest-wide through LDAP. The bind uses the existing Kerberos ticket. Use when the user asks "who is X", needs someone's title / department / manager / email, or wants to disambiguate a name. For the *current* user's own identity, use the sibling `person-identify` skill instead.
 ---
 
 # Person Lookup
 
 Resolve **any** person in the corporate Active Directory from natural-language
-input — an email, a login, or any part of a name. The sibling of
-`person-identify`, but aimed at *other* people: it searches the **Global
-Catalog** (forest-wide), handles multiple matches, flags external contacts and
-vendor accounts, and — unlike `person-identify` — never writes the identity
-cache. It's a read-only, throwaway lookup.
+input. The input is an email, a login, or any part of a name. This skill is the
+sibling of `person-identify`, and it aims at *other* people. It searches the
+**Global Catalog** (forest-wide). It handles multiple matches. It flags
+external contacts and vendor accounts. Unlike `person-identify`, it never
+writes the identity cache. It is a read-only, throwaway lookup.
 
 ## Trigger
 
 - The user asks "who is <name>", or for someone's title, department, manager,
   email, or employee ID.
-- A name is ambiguous and needs disambiguating against the directory.
+- A name is ambiguous, and you must disambiguate it against the directory.
 - Another skill needs to resolve a person who is **not** the current user.
 
-For the current user's own record (and to populate the identity cache that other
-skills read), use `person-identify` instead.
+For the current user's own record, use `person-identify` instead. It also
+populates the identity cache that other skills read.
 
 ## Prerequisites
 
-- A valid **Kerberos ticket** (`klist` shows a principal). If absent:
+- A valid **Kerberos ticket** (`klist` shows a principal). If absent, run
   `kinit <user>@<REALM>`.
-- Network reachability to a domain controller (on-site or VPN).
-- `ldapsearch` and `dig` — both ship with macOS; nothing to install.
+- Network access to a domain controller (on-site or VPN).
+- `ldapsearch` and `dig` — both ship with macOS. You install nothing.
 
-Nothing is hardcoded: the realm and a domain controller are derived at runtime
-from the ticket and DNS. The bind uses SASL/GSSAPI against the existing ticket —
-no password is ever entered.
+Nothing is hardcoded. The script derives the realm and a domain controller at
+runtime from the ticket and DNS. The bind uses SASL/GSSAPI against the existing
+ticket. You never enter a password.
 
 ## Usage
 
@@ -44,20 +44,20 @@ The argument is free text: an email, a full name, or just a surname.
 
 ## How it works
 
-1. **Derive a domain controller** from the Kerberos principal's realm via DNS
-   SRV (same bootstrap as `person-identify`).
+1. **Derive a domain controller** from the Kerberos principal's realm through
+   DNS SRV (same bootstrap as `person-identify`).
 2. **Search the Global Catalog** (`ldap://$dc:3268`, base `""`). The GC spans
-   *every* domain in the forest, so a colleague in another region is found from
-   your own ticket — a plain domain-scoped search would miss them. It also
+   *every* domain in the forest. So you find a colleague in another region from
+   your own ticket. A plain domain-scoped search would miss them. It also
    returns the common attributes (title, department, mail, manager), so one
    query is enough.
-3. **Match with ANR** (Ambiguous Name Resolution): the `(anr=<input>)` filter
+3. **Match with ANR** (Ambiguous Name Resolution). The `(anr=<input>)` filter
    matches an email, a login, or any name part in one shot. If ANR finds
    nothing, fall back to a substring search on `mail` / `displayName` /
    `proxyAddresses`.
 4. **Resolve per match.** For a single hit, print the full record and resolve
    the `manager` DN to a name. For several hits, print a compact
-   disambiguation list and suggest narrowing by email.
+   disambiguation list and suggest a narrower search by email.
 
 ## Output
 
@@ -80,18 +80,17 @@ The argument is free text: an email, a full name, or just a surname.
   external **Contact** object (e.g. a vendor email alias), returns several
   entries. The **Type** column distinguishes an internal **Employee** from an
   external **Contact** (standard `objectClass=contact`). Some directories also
-  park external/vendor *user* accounts under a dedicated OU; set
+  park external/vendor *user* accounts under a dedicated OU. Set
   `VENDOR_OU_PATTERN` at the top of `scripts/lookup.sh` to your directory's OU
-  substring (e.g. `OU=Contractors`) to flag those too. It is empty by default,
-  since the OU convention is organization-specific. Narrow with an email for an
-  exact hit.
+  substring (e.g. `OU=Contractors`). This flags those accounts too. It is empty
+  by default, since the OU convention is organization-specific. Narrow with an
+  email for an exact hit.
 - **Silent partial results.** Under load the directory occasionally returns an
   entry's DN with no attributes (exit 0, no error). Every attribute fetch
   retries with backoff, so a throttled response never masquerades as a person
   with a blank title or email.
 - **No cache.** This skill prints and exits. It never touches
-  `~/.cache/fit/outpost/state/identity.md` — that file is owned solely by
-  `person-identify`.
+  `~/.cache/fit/outpost/state/identity.md`. `person-identify` owns that file
+  alone.
 - **Ethics.** This reads objective, work-relevant directory data only, in line
-  with the knowledge base's integrity rules. It is not a tool for building
-  dossiers.
+  with the knowledge base's integrity rules. Never use it to build dossiers.