@forwardimpact/outpost 3.12.0 → 3.13.0

package/templates/.claude/skills/doc-create/SKILL.md

@@ -1,14 +1,17 @@
 ---
 name: doc-create
-description: Generate PDF documents from user requests using Playwright to render HTML to A4 PDF. Use when the user asks to create a document, proposal, report, or any multi-page PDF that is not a slide deck. Pulls context from the knowledge base for company info, project details, and people.
+description: Generate PDF documents from user requests. Playwright renders the HTML to an A4 PDF. Use when the user asks to create a document, proposal, report, or any multi-page PDF that is not a slide deck. Pulls context from the knowledge base for company info, project details, and people.
 compatibility: Requires Node.js installed. Playwright is installed on first use.
 ---
 
 # Create Documents
 
-Generate multi-page A4 PDF documents from user requests. Uses Playwright to
-render self-contained HTML to PDF. Can pull context from the knowledge base for
-company info, project details, and people.
+Write tier: `0-Draft`
+Frontmatter: none
+
+Generate multi-page A4 PDF documents from user requests. This skill uses
+Playwright to render self-contained HTML to PDF. It can pull context from the
+knowledge base for company info, project details, and people.
 
 ## Trigger
 
@@ -18,39 +21,39 @@ submission, brief, or any multi-page PDF that is not a slide deck.
 ## Prerequisites
 
 - Node.js installed
-- Playwright will be installed on first use
+- Playwright installs on first use
 
 ## Inputs
 
 - User's description of the document
-- `Knowledge/` — optional context about company, product, team, projects
+- `3-Team/` — optional context about company, product, team, projects
 
 ## Outputs
 
 - An HTML file and a PDF rendered from it, placed where the user specifies
-  (default: `Knowledge/Projects/`)
+  (default: `0-Draft/`; the human promotes a finished document into its tier)
 
 ---
 
 ## Workflow
 
-1. Check `Knowledge/` for relevant context about the company, product, team,
+1. Check `3-Team/` for relevant context about the company, product, team,
    projects, or people mentioned.
-2. Ensure Playwright is installed:
+2. Make sure Playwright is installed:
    `bun install playwright && bunx playwright install chromium`
 3. Create a self-contained HTML file with all CSS inlined. The HTML must handle
-   its own page layout — see **HTML Document Rules** below.
+   its own page layout. See **HTML Document Rules** below.
 4. Run the conversion script:
 
    ```text
     node .claude/skills/doc-create/scripts/convert-to-pdf.mjs <input.html> [output.pdf]
    ```
 
-   If output is omitted, the PDF is written alongside the HTML file with the
-   same name.
+   If you omit the output path, the script writes the PDF next to the HTML file
+   with the same name.
 5. Read the PDF back to visually verify it renders correctly. Check each page
-   for overflow, clipped content, and correct page breaks. Fix and re-render if
-   needed.
+   for overflow, clipped content, and correct page breaks. If you find a
+   problem, fix it and re-render.
 
 **Do NOT show HTML code to the user. Just create the PDF and deliver it.**
 
@@ -60,8 +63,9 @@ submission, brief, or any multi-page PDF that is not a slide deck.
 
 - Each page is a `<div class="page">` sized to exactly 210mm × 297mm (A4)
 - Use `page-break-after: always` on every `.page` except the last
-- Handle margins with padding inside `.page`, not with PDF margin settings
-- The PDF is rendered with zero margins — the HTML owns all spacing
+- Handle margins with padding inside `.page` rather than with PDF margin
+  settings
+- Playwright renders the PDF with zero margins, so the HTML owns all spacing
 
 **Print colours:**
 
@@ -70,16 +74,16 @@ submission, brief, or any multi-page PDF that is not a slide deck.
 
 **Fonts:**
 
-- Use system fonts only — no external font loading
+- Use system fonts only, and do not load an external font
 - Monospace stack: `'SF Mono', 'Menlo', 'Monaco', 'Consolas', monospace`
 - Sans-serif stack:
   `-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif`
 
-**Content fitting:**
+**Content fit:**
 
 - After the first render, visually check every page for overflow
-- Content must not bleed past the `.page` boundary — if it does, reduce spacing
-  or font sizes and re-render
+- Content must not bleed past the `.page` boundary. If it does, reduce spacing
+  or font sizes, then re-render
 - Page numbers, if used, must not overlap with content. Position them in a
   corner that has whitespace
 
@@ -93,14 +97,14 @@ submission, brief, or any multi-page PDF that is not a slide deck.
 
 - Use absolute `file://` paths for local images
 - Inline small images as base64 data URIs when possible
-- Verify images appear in the rendered PDF — Playwright can fail silently on
-  missing images
+- Verify images appear in the rendered PDF, because Playwright can fail silently
+  on missing images
 
 ## Design Principles
 
 - Clean, professional typography with clear hierarchy
 - Use monospace for section headers and numbers for a technical/engineering feel
-- Tables should be compact and readable — right-align monetary values
+- Keep tables compact and readable, and right-align monetary values
 - Use colour sparingly: one accent colour, one dark, lots of white space
 - Dark-background panels (timelines, hero sections) create visual contrast
 - Callout boxes with left borders draw attention to key statements

package/templates/.claude/skills/doc-create/scripts/convert-to-pdf.mjs

@@ -1,18 +1,18 @@
 #!/usr/bin/env bun
 /**
- * Convert an HTML document to A4 PDF using Playwright.
+ * Convert an HTML document to an A4 PDF with Playwright.
  *
- * Renders an HTML file into an A4 PDF with background colours preserved and
- * zero margins (the HTML is expected to handle its own page layout via CSS
- * @page rules and page-break-after). Defaults to writing the PDF alongside
- * the input file when no output path is given.
+ * The script renders an HTML file into an A4 PDF. It keeps the background
+ * colours. It sets zero margins. The script expects the HTML to handle its own
+ * page layout through CSS @page rules and page-break-after. Without an output
+ * path, the script writes the PDF next to the input file.
  *
  * Requires: bun install playwright && bunx playwright install chromium
  */
 
 import { resolve, dirname, basename, join } from "node:path";
 
-const HELP = `convert-to-pdf — render an HTML document to A4 PDF via Playwright
+const HELP = `convert-to-pdf — render an HTML document to A4 PDF with Playwright
 
 Usage: bun scripts/convert-to-pdf.mjs <input.html> [output.pdf] [-h|--help]
 

package/templates/.claude/skills/draft-emails/SKILL.md

@@ -1,13 +1,16 @@
 ---
 name: draft-emails
-description: Draft and send email responses using the knowledge base and calendar for context. Use when the user asks to draft, reply to, respond to, or send an email.
+description: Draft and send email responses with context from the knowledge base and calendar. Use when the user asks to draft, reply to, respond to, or send an email.
 ---
 
 # Draft Emails
 
-Draft and send email responses using the knowledge base and calendar for full
-context on every person and conversation. Every draft requires explicit user
-approval before sending.
+Write tier: `0-Draft`
+Frontmatter: none
+
+Draft and send email responses. Use the knowledge base and calendar for full
+context on every person and conversation. Every draft needs explicit user
+approval before you send it.
 
 ## Trigger
 
@@ -20,32 +23,36 @@ The user asks to draft, reply to, respond to, or send an email.
 
 ## Data locations
 
-| Data            | Location                                     |
-| --------------- | -------------------------------------------- |
-| People          | `Knowledge/People/*.md`                      |
-| Organizations   | `Knowledge/Organizations/*.md`               |
-| Email threads   | `~/.cache/fit/outpost/apple_mail/*.md`       |
-| Calendar events | `~/.cache/fit/outpost/apple_calendar/*.json` |
-| Handled IDs     | `Drafts/handled` (one ID per line)           |
-| Ignored IDs     | `Drafts/ignored` (one ID per line)           |
-| Draft files     | `Drafts/{email_id}_draft.md`                 |
+| Data            | Location                                            |
+| --------------- | --------------------------------------------------- |
+| People          | `3-Team/People/*.md`                                 |
+| Organizations   | `3-Team/Organizations/*.md`                          |
+| Email threads   | `~/.cache/fit/outpost/apple_mail/*.md`               |
+| Calendar events | `~/.cache/fit/outpost/apple_calendar/*.json`         |
+| Handled IDs     | `~/.cache/fit/outpost/drafts/handled` (one ID/line)  |
+| Ignored IDs     | `~/.cache/fit/outpost/drafts/ignored` (one ID/line)  |
+| Draft files     | `0-Draft/{email_id}_draft.md`                        |
 
 `handled` and `ignored` both exclude threads from `scan-emails.mjs`. Use
-`handled` for resolved threads (sent here, replied manually, resolved via DM);
-`ignored` for threads that need no response (newsletters, spam, outbound with no
-reply).
+`handled` for resolved threads (sent here, replied manually, resolved through a
+DM). Use `ignored` for threads that need no response (newsletters, spam,
+outbound with no reply). The ledgers are agent state, not knowledge. They live
+in the cache `drafts/` directory, never in `state/` (a daemon-owned trust
+root).
 
 <do_confirm_checklist goal="Verify a draft is safe and ready before sending">
 
-- [ ] Sender and organization were looked up in `Knowledge/` before drafting.
-- [ ] Draft is a single email (not multiple variants) and matches the incoming
-      tone.
-- [ ] Body has no sign-off / name / "Best" — Apple Mail signature handles it.
-- [ ] Recruitment thread: candidate excluded from internal recipients; any
-      direct-to-candidate draft is flagged `⚠️ RECRUITER ONLY`.
-- [ ] No sensitive personal data (health, politics, etc.) was included.
-- [ ] User has explicitly approved the draft before any send.
-- [ ] Send used `--draft <path>` so cleanup and `Drafts/handled` happen
+- [ ] You looked up the sender and the organization in `3-Team/` before you
+      drafted.
+- [ ] The draft is a single email (not multiple variants). It matches the
+      incoming tone.
+- [ ] The body has no sign-off, name, or "Best". The Apple Mail signature
+      handles it.
+- [ ] In a recruitment thread, the candidate is excluded from internal
+      recipients. Any direct-to-candidate draft carries `⚠️ RECRUITER ONLY`.
+- [ ] The draft includes no sensitive personal data (health, politics, etc.).
+- [ ] The user explicitly approved the draft before any send.
+- [ ] Send used `--draft <path>` so cleanup and the `handled` ledger happen
       automatically.
 
 </do_confirm_checklist>
@@ -58,65 +65,67 @@ reply).
 node scripts/scan-emails.mjs
 ```
 
-Outputs `email_id<TAB>subject` for unprocessed emails (those not in
-`Drafts/handled` or `Drafts/ignored`).
+The script outputs `email_id<TAB>subject` for unprocessed emails (those not in
+the `handled` or `ignored` ledger).
 
 ### 2. Classify
 
-**Ignore** (append ID to `Drafts/ignored`): newsletters, marketing, automated
-notifications, spam, outbound with no reply.
+**Ignore** (append the ID to `~/.cache/fit/outpost/drafts/ignored`):
+newsletters, marketing, automated notifications, spam, outbound with no reply.
 
 **Draft a response**: meeting requests, personal mail from known contacts,
 business inquiries or follow-ups, requests for information or action.
 
-Be conservative with ignore — when in doubt, draft.
+Be conservative with ignore. When in doubt, draft.
 
 ### 3. Gather context
 
-Before drafting, look up the sender and organization in `Knowledge/`:
+Before you draft, look up the sender and the organization in the graph:
 
 ```bash
-rg -l "sender_name" Knowledge/
-cat "Knowledge/People/Sender Name.md"
-cat "Knowledge/Organizations/Company Name.md"
+rg -l "sender_name" [0-9]-*/
+cat "3-Team/People/Sender Name.md"
+cat "3-Team/Organizations/Company Name.md"
 ```
 
-For scheduling emails, also read the relevant calendar event:
+For an email that arranges a meeting time, also read the relevant calendar
+event:
 
 ```bash
 ls ~/.cache/fit/outpost/apple_calendar/ 2>/dev/null
 cat "$HOME/.cache/fit/outpost/apple_calendar/event123.json"
 ```
 
-Extract role, organization, relationship history, and open items. If intent is
-unclear or the person has multiple contexts, **ask** rather than guess.
+Extract role, organization, relationship history, and open items. If the intent
+is unclear or the person has multiple contexts, **ask** rather than guess.
 
 ### 4. Write the draft
 
-Save to `Drafts/{email_id}_draft.md` using the template in
+Save to `0-Draft/{email_id}_draft.md` with the template in
 [references/template.md](references/template.md). Reference past interactions
-naturally; for scheduling, propose specific times from calendar availability.
+naturally. To arrange a meeting, propose specific times from the calendar
+availability.
 
 ### 5. Recruitment & staffing emails
 
-Candidates **must never** be copied on internal threads about them.
+You **must never** copy candidates on internal threads about them.
 
-- Identify the candidate from the thread and `Knowledge/Candidates/`.
-- Strip the candidate from To/CC; draft to internal stakeholders only.
+- Identify the candidate from the thread and `2-Confidential/Candidates/`.
+- Strip the candidate from To/CC. Draft to internal stakeholders only.
 - Direct-to-candidate emails carry the warning header
   `⚠️ RECRUITER ONLY — This email goes directly to the candidate.`
 
 If a thread mentions a candidate and includes multiple internal recipients,
-treat it as internal and exclude the candidate.
+treat it as internal. Exclude the candidate.
 
 ### 6. Present and approve
 
-Show the draft to the user. Wait for explicit approval before sending. Apply
-edits and present again as needed.
+Show the draft to the user. Wait for explicit approval before you send. Apply
+edits. Present the draft again as needed.
 
 ### 7. Send
 
-After approval, send via Apple Mail:
+After the user approves, send the email through Apple Mail:
 
 ```bash
 node scripts/send-email.mjs \
@@ -124,18 +133,19 @@ node scripts/send-email.mjs \
   --cc "other@example.com" \
   --subject "Re: Subject" \
   --body "Plain text body" \
-  --draft "Drafts/12345_draft.md"
+  --draft "0-Draft/12345_draft.md"
 ```
 
 Required: `--to`, `--subject`, `--body` (plain text). Optional: `--cc`, `--bcc`,
-`--draft`. With `--draft`, the draft file is deleted and the email ID is
-appended to `Drafts/handled` automatically.
+`--draft`. With `--draft`, the script deletes the draft file. It also appends
+the email ID to the `handled` ledger automatically.
 
-### 8. Mark handled without sending
+### 8. Mark handled and do not send
 
-When a thread is resolved through other channels:
+When other channels resolve a thread:
 
 ```bash
-echo "$EMAIL_ID" >> Drafts/handled
-rm -f "Drafts/${EMAIL_ID}_draft.md"
+mkdir -p ~/.cache/fit/outpost/drafts
+echo "$EMAIL_ID" >> ~/.cache/fit/outpost/drafts/handled
+rm -f "0-Draft/${EMAIL_ID}_draft.md"
 ```

package/templates/.claude/skills/draft-emails/references/template.md

@@ -1,6 +1,6 @@
 # Draft File Template
 
-Save each draft to `Drafts/{email_id}_draft.md` using this layout:
+Save each draft to `0-Draft/{email_id}_draft.md` with this layout:
 
 ```markdown
 # Draft Response
@@ -22,5 +22,5 @@ Save each draft to `Drafts/{email_id}_draft.md` using this layout:
 ```
 
 The body must end with the last sentence of content. Apple Mail appends the
-user's configured signature automatically, so do **not** add a sign-off, "Best",
+user's configured signature automatically. So do **not** add a sign-off, "Best",
 "Cheers", or the user's name.

package/templates/.claude/skills/draft-emails/scripts/scan-emails.mjs

@@ -2,13 +2,17 @@
 /**
  * Scan for unprocessed emails and output their IDs and subjects.
  *
- * Checks ~/.cache/fit/outpost/apple_mail/ for email thread markdown files not
- * yet listed in Drafts/handled or Drafts/ignored. Outputs one tab-separated
- * line per unprocessed thread: email_id<TAB>subject. Used by the draft-emails
- * skill to identify threads that need a reply.
+ * The script checks ~/.cache/fit/outpost/apple_mail/ for email thread markdown
+ * files. It skips a file that the ~/.cache/fit/outpost/drafts/handled or
+ * ~/.cache/fit/outpost/drafts/ignored ledger already lists. It outputs one
+ * tab-separated line per unprocessed thread: email_id<TAB>subject. The
+ * draft-emails skill uses this script to find threads that need a reply.
+ *
+ * The ledgers live in the cache drafts/ directory. Never move them into
+ * ~/.cache/fit/outpost/state/ — that directory is a daemon-owned trust root.
  */
 
-import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync } from "node:fs";
 import { basename, join } from "node:path";
 import { homedir } from "node:os";
 
@@ -17,7 +21,8 @@ const HELP = `scan-emails — list unprocessed email threads
 Usage: node scripts/scan-emails.mjs [-h|--help]
 
 Scans ~/.cache/fit/outpost/apple_mail/ for .md thread files not yet
-recorded in Drafts/handled or Drafts/ignored. Outputs one line per
+recorded in ~/.cache/fit/outpost/drafts/handled or
+~/.cache/fit/outpost/drafts/ignored. Outputs one line per
 unprocessed thread as: email_id<TAB>subject`;
 
 if (process.argv.includes("-h") || process.argv.includes("--help")) {
@@ -27,6 +32,7 @@ if (process.argv.includes("-h") || process.argv.includes("--help")) {
 
 const HOME = homedir();
 const MAIL_DIR = join(HOME, ".cache/fit/outpost/apple_mail");
+const DRAFTS_DIR = join(HOME, ".cache/fit/outpost/drafts");
 
 /** Load a file of IDs (one per line) into a Set. */
 function loadIdSet(path) {
@@ -49,8 +55,9 @@ function extractSubject(filePath) {
 function main() {
   if (!existsSync(MAIL_DIR)) return;
 
-  const handled = loadIdSet("Drafts/handled");
-  const ignored = loadIdSet("Drafts/ignored");
+  mkdirSync(DRAFTS_DIR, { recursive: true });
+  const handled = loadIdSet(join(DRAFTS_DIR, "handled"));
+  const ignored = loadIdSet(join(DRAFTS_DIR, "ignored"));
 
   for (const name of readdirSync(MAIL_DIR).sort()) {
     if (!name.endsWith(".md")) continue;

package/templates/.claude/skills/draft-emails/scripts/send-email.mjs

@@ -1,26 +1,29 @@
 #!/usr/bin/env bun
 /**
- * Send an email via Apple Mail using AppleScript.
+ * Send an email through Apple Mail with AppleScript.
  *
- * Builds an AppleScript command to create and send an outgoing message through
- * Apple Mail. The script writes a temporary .scpt file, executes it with
- * osascript, and cleans up afterwards. Mail.app must be running.
+ * The script builds an AppleScript command. That command creates an outgoing
+ * message and sends it through Apple Mail. The script writes a temporary
+ * .scpt file. It runs the file with osascript. It then deletes the file.
+ * Mail.app must run.
  *
- * The body should be plain text — no HTML. Do NOT include an email signature
- * or sign-off; Apple Mail appends the user's configured signature automatically.
+ * Use plain text for the body. Do not use HTML. Do NOT include an email
+ * signature or sign-off. Apple Mail appends the user's configured signature
+ * automatically.
  */
 
 import { execFileSync } from "node:child_process";
 import {
   appendFileSync,
+  mkdirSync,
   mkdtempSync,
   writeFileSync,
   unlinkSync,
 } from "node:fs";
 import { basename, join } from "node:path";
-import { tmpdir } from "node:os";
+import { homedir, tmpdir } from "node:os";
 
-const HELP = `send-email — send an email via Apple Mail
+const HELP = `send-email — send an email through Apple Mail
 
 Usage: node scripts/send-email.mjs --to <addrs> --subject <subj> --body <text> [options]
 
@@ -30,10 +33,10 @@ Options:
   --bcc <addrs>      Comma-separated BCC recipients
   --subject <subj>   Email subject line (required)
   --body <text>      Plain-text email body (required)
-  --draft <path>     Draft file — deleted after send, ID appended to Drafts/handled
+  --draft <path>     Draft file. The script deletes it after send and appends the ID to ~/.cache/fit/outpost/drafts/handled
   -h, --help         Show this help message and exit
 
-Mail.app must be running. No signature or sign-off needed — Apple Mail appends it.`;
+Mail.app must run. You need no signature or sign-off. Apple Mail appends it.`;
 
 if (process.argv.includes("-h") || process.argv.includes("--help")) {
   console.log(HELP);
@@ -102,6 +105,10 @@ function buildAppleScript({ to, cc, bcc, subject, body }) {
     .join("\n");
 }
 
+// The handled ledger lives in the cache drafts/ directory. Never move it into
+// ~/.cache/fit/outpost/state/ — that directory is a daemon-owned trust root.
+const DRAFTS_DIR = join(homedir(), ".cache/fit/outpost/drafts");
+
 function handleDraftCleanup(draft) {
   if (!draft) return;
   try {
@@ -113,7 +120,8 @@ function handleDraftCleanup(draft) {
   const draftBasename = basename(draft, ".md");
   const emailId = draftBasename.replace(/_draft$/, "");
   if (emailId) {
-    appendFileSync("Drafts/handled", emailId + "\n");
+    mkdirSync(DRAFTS_DIR, { recursive: true });
+    appendFileSync(join(DRAFTS_DIR, "handled"), emailId + "\n");
     console.log(`Marked as handled: ${emailId}`);
   }
 }