@forwardimpact/outpost 3.5.1 → 3.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardimpact/outpost",
-  "version": "3.5.1",
+  "version": "3.7.0",
   "description": "Personal operations center — context from email, calendar, and knowledge assembled so preparation is continuous, not a morning scramble.",
   "homepage": "https://www.forwardimpact.team",
   "repository": {

package/src/kb-manager.js

@@ -189,7 +189,7 @@ export class KBManager {
     await this.copyBundledFiles(templateDir, dest);
 
     this.#logger.info(
-      `Knowledge base initialized at ${dest}\n\nNext steps:\n  1. cd ${dest} && npx apm install\n  2. claude\n  3. Run the identify-user skill to populate your identity`,
+      `Knowledge base initialized at ${dest}\n\nNext steps:\n  1. cd ${dest} && npx apm install\n  2. claude\n  3. Run the person-identify skill to populate your identity`,
     );
     return { ok: true, value: { dest } };
   }

package/src/outpost.js

@@ -26,7 +26,7 @@ import { StateManager } from "./state-manager.js";
 import { AgentRunner } from "./agent-runner.js";
 import { Scheduler, formatLocalTime } from "./scheduler.js";
 import { KBManager } from "./kb-manager.js";
-import { SocketServer, requestShutdown } from "./socket-server.js";
+import { SocketServer, requestShutdown, requestWake } from "./socket-server.js";
 import {
   readPosture,
   writePosture,
@@ -436,17 +436,28 @@ export async function run(runtime, version) {
         cli.usageError("missing required argument <agent>");
         return 2;
       }
-      const config = await loadConfig();
-      const state = await stateManager.load();
-      const agent = config.agents[args[0]];
-      if (!agent) {
+      // Always route the wake through the running daemon. The daemon is the
+      // only spawn site that descends from fit-outpost.app, so a `claude`
+      // spawned there inherits the app as its TCC responsible process and a
+      // single grant to the app covers it. Spawning from this CLI process
+      // would attribute the access to the terminal instead, breaking the
+      // single-grant model. If no daemon is running there is nowhere to wake
+      // with correct attribution, so this errors rather than spawning locally.
+      const result = await requestWake(SOCKET_PATH, args[0], runtime);
+      if (result.ok) {
+        log(`Wake dispatched to daemon for "${args[0]}".`);
+        return 0;
+      }
+      if (result.reason === "not-running") {
         cli.error(
-          `agent "${args[0]}" not found. Available: ${Object.keys(config.agents).join(", ") || "(none)"}`,
+          "daemon not running. Start fit-outpost.app (or run `fit-outpost daemon`) before waking an agent.",
         );
-        return 1;
+      } else if (result.reason === "timeout") {
+        cli.error("daemon did not respond to the wake request.");
+      } else {
+        cli.error(result.message);
       }
-      await agentRunner.wake(args[0], agent, state, config.env);
-      return 0;
+      return 1;
     },
     init: async () => {
       if (!args[0]) {

package/src/socket-server.js

@@ -323,6 +323,71 @@ export class SocketServer {
   }
 }
 
+/**
+ * Connect to the running daemon and ask it to wake an agent.
+ *
+ * The wake runs inside the daemon process, which is the only spawn site that
+ * descends from fit-outpost.app — so the spawned `claude` inherits the app as
+ * its TCC responsible process. Routing every wake through the daemon is what
+ * keeps the single-grant model intact; a wake spawned from this CLI process
+ * would be attributed to the terminal instead. The daemon acknowledges
+ * (`ack`) once it has accepted the request and then runs the wake
+ * asynchronously, so this resolves on the ack rather than on completion.
+ *
+ * @param {string} socketPath
+ * @param {string} agent - Agent name to wake.
+ * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
+ *   Injected runtime bag (uses `fsSync` and `clock`).
+ * @returns {Promise<{ ok: boolean, reason?: "not-running"|"timeout"|"error", message?: string }>}
+ */
+export async function requestWake(socketPath, agent, runtime) {
+  if (!runtime?.fsSync) throw new Error("runtime.fsSync is required");
+  if (!runtime?.clock) throw new Error("runtime.clock is required");
+  if (!runtime.fsSync.existsSync(socketPath)) {
+    return { ok: false, reason: "not-running" };
+  }
+
+  return new Promise((resolve) => {
+    const timeout = runtime.clock.setTimeout(() => {
+      socket.destroy();
+      resolve({ ok: false, reason: "timeout" });
+    }, 5000);
+
+    const socket = createConnection(socketPath, () => {
+      socket.write(JSON.stringify({ type: "wake", agent }) + "\n");
+    });
+
+    let buffer = "";
+    socket.on("data", (data) => {
+      buffer += data.toString();
+      const idx = buffer.indexOf("\n");
+      if (idx === -1) return;
+      runtime.clock.clearTimeout(timeout);
+      let msg = null;
+      try {
+        msg = JSON.parse(buffer.slice(0, idx));
+      } catch {}
+      socket.destroy();
+      if (msg && msg.type === "ack" && msg.command === "wake") {
+        resolve({ ok: true });
+      } else {
+        resolve({
+          ok: false,
+          reason: "error",
+          message: msg?.message || "daemon rejected wake request",
+        });
+      }
+    });
+
+    // A stale socket file (daemon crashed) refuses the connection; treat it
+    // the same as a missing daemon.
+    socket.on("error", () => {
+      runtime.clock.clearTimeout(timeout);
+      resolve({ ok: false, reason: "not-running" });
+    });
+  });
+}
+
 /**
  * Connect to the daemon socket and request graceful shutdown.
  * @param {string} socketPath

package/templates/.claude/skills/anarlog-process/SKILL.md

@@ -20,7 +20,7 @@ same way `extract-entities` processes emails and calendar events.
 
 - Anarlog installed; sessions at
   `~/Library/Application Support/anarlog/sessions/`.
-- User identity from running the `identify-user` skill, which writes
+- User identity from running the `person-identify` skill, which writes
   `~/.cache/fit/outpost/state/identity.md`.
 
 ## Inputs
@@ -31,7 +31,7 @@ same way `extract-entities` processes emails and calendar events.
 - `~/.cache/fit/outpost/state/graph_processed` — processed-file index (TSV,
   shared with `extract-entities`).
 - `~/.cache/fit/outpost/state/identity.md` — user identity for self-exclusion
-  (written by the `identify-user` skill).
+  (written by the `person-identify` skill).
 
 ## Outputs
 
@@ -62,7 +62,7 @@ same way `extract-entities` processes emails and calendar events.
 ### 0. Set up
 
 Read the user's identity from `~/.cache/fit/outpost/state/identity.md` (run the
-`identify-user` skill first if it is missing or stale). Scan unprocessed
+`person-identify` skill first if it is missing or stale). Scan unprocessed
 sessions:
 
 ```bash

package/templates/.claude/skills/changelog/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: changelog
+description: Record the knowledge-graph changes made during the current session into a single shared Knowledge/CHANGELOG.md so the team can see what changed and why. Use when the user asks to log, record, or write up the changes they just made to the knowledge base — typically at the end of a session of edits.
+---
+
+# Changelog
+
+Record the changes made to the **knowledge graph** (`Knowledge/`) during the
+current working session in one shared `Knowledge/CHANGELOG.md`, newest first, so
+teammates syncing the same filesystem can see what changed and why.
+
+This tracks **graph content** — notes under `Knowledge/People/`,
+`Organizations/`, `Projects/`, `Topics/`, `Candidates/`, `Priorities/`, and the
+other subdirectories. It does **not** track changes to instructions (`CLAUDE.md`,
+agents, skills) — that is the `upstream-instructions` skill's job.
+
+## Trigger
+
+- The user asks to write, update, or record a changelog after editing the KB.
+- A session has added, modified, removed, or renamed notes in `Knowledge/` and
+  the user wants those changes documented for the team.
+
+## Inputs
+
+- **The edits made in the current session** — the source of truth. The KB lives
+  on a synced filesystem and is not version-controlled, so there is no commit
+  history to diff. Recall every note created, edited, removed, or renamed under
+  `Knowledge/` during this conversation.
+- `~/.cache/fit/outpost/state/identity.md` — the current user's identity. Its
+  **Name** is the author recorded on each entry. The KB is shared, so every
+  change must be attributed to the team member who made it. Resolve `~` to
+  `$HOME` before reading.
+- `Knowledge/CHANGELOG.md` — the existing changelog, to see what's already
+  recorded and avoid duplicates.
+
+## Outputs
+
+- `Knowledge/CHANGELOG.md` — a **single** reverse-chronological changelog
+  covering all graph subdirectories. No per-folder or per-note changelogs.
+
+## Ethics
+
+`Knowledge/` is shared with the team. Every entry obeys the KB's integrity rules:
+objective and factual, work-relevant, no personal judgments. Assume the person a
+note is about will read its changelog entry. Describe **what changed in the
+graph**, not opinions about the people in it.
+
+<do_confirm_checklist goal="Verify the changelog is accurate and shareable">
+
+- [ ] Exactly one `Knowledge/CHANGELOG.md`; no stray per-folder changelogs.
+- [ ] Every entry names its **Scope** — the specific note(s) or folder(s) touched,
+      by full path.
+- [ ] Each entry has **Who** (author, from identity), **What**, and **Why**.
+- [ ] Descriptions are specific enough to be useful (not "updated some notes").
+- [ ] Dates are the date the change was actually made, not guessed.
+- [ ] No duplicate entries for a change already in the changelog.
+- [ ] Entries are factual and would be fine for the subject to read.
+
+</do_confirm_checklist>
+
+## Procedure
+
+### 1. Find what's already recorded, and who you are
+
+```bash
+head -30 Knowledge/CHANGELOG.md 2>/dev/null     # newest date already logged, if any
+cat "$HOME/.cache/fit/outpost/state/identity.md"  # Name → the author for this session's entries
+```
+
+If `identity.md` is missing or stale, run the `person-identify` skill to refresh
+it before logging — don't guess the author.
+
+### 2. Reconstruct this session's changes
+
+Recall every change made to `Knowledge/` during the current conversation:
+creations, edits, removals, renames. Group them by note. If you are unsure a
+change landed, confirm it before logging:
+
+```bash
+rg --files Knowledge/ | rg "<note name>"        # confirm a note exists
+cat "Knowledge/People/Doe, Jane.md"             # confirm content landed
+```
+
+Optionally surface anything edited recently that you might have missed:
+
+```bash
+find Knowledge -name '*.md' -newermt '-1 day' -not -path '*/.*'
+```
+
+Use `Knowledge/CHANGELOG.md` only to avoid duplicating an entry already there.
+
+### 3. Classify each change
+
+| Type       | Description                          |
+| ---------- | ------------------------------------ |
+| `added`    | New note created                     |
+| `modified` | Existing note updated                |
+| `removed`  | Note deleted                         |
+| `renamed`  | Note renamed or moved                |
+
+Related changes that form one logical edit (e.g. a new project note plus the
+backlinks added to the people it involves) are recorded as **one entry** whose
+Scope lists every note touched.
+
+### 4. Write the changelog
+
+Create or update `Knowledge/CHANGELOG.md` (newest first). Group entries under one
+heading per day; one bullet per logical change:
+
+```markdown
+# Knowledge Changelog
+
+Changes to the shared knowledge graph, newest first. Maintained by hand at the
+end of editing sessions via the `changelog` skill. The KB is not
+version-controlled, so this is the record of what changed and why.
+
+## <YYYY-MM-DD>
+
+- **<added | modified | removed | renamed>** — _<Scope: full path(s)>_ · <Who>
+  **What:** <one-line summary of the change.>
+  **Why:** <the reason — the email, meeting, or request that prompted it.>
+```
+
+Use the real date the change was made (today's date is in context) and the
+**Name** from `identity.md` as `<Who>`. Because the file is shared, the author
+travels on each entry — not just the day's heading — so a day with edits from
+more than one teammate stays unambiguous. Keep each entry to its What and Why —
+this is a ledger, not a diff.
+
+## Notes
+
+- This skill **documents only** — it records changes already made; it does not
+  make or undo edits.
+- One `Knowledge/CHANGELOG.md` at the graph root, never per-folder.
+- For changes to instructions (`CLAUDE.md`, agents, skills), use
+  `upstream-instructions` instead.

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

@@ -67,9 +67,49 @@ Defaults: input = `/tmp/outpost-presentation.html`, output =
 5. **No footers or headers** — No fixed/absolute positioned footer/header
    elements
 
+## Interactive HTML Decks — Navigation & Event Standards
+
+When the deck is delivered as a **standalone interactive HTML file** (animated /
+navigable in the browser) rather than a static PDF, keep input handling
+deliberately minimal. Rich event handling fights with two things the user needs:
+selecting/copying text on a slide, and typing into overlay tools (e.g. the
+`slide-annotator.js` review overlay).
+
+**Required:**
+
+1. **Arrow keys are the only navigation.** `→` / `ArrowRight` = next,
+   `←` / `ArrowLeft` = previous. Nothing else advances slides.
+2. **No click-to-advance.** Do NOT add click regions on the slide/stage that
+   navigate (e.g. "click left/right third"). They fire on the mouse-up that ends
+   a text-selection drag and jump the slide unexpectedly.
+3. **No spacebar, PageUp/PageDown, or other global key bindings.** Space conflicts
+   with typing in overlay inputs; the rest are redundant and surprising.
+4. **A progress indicator may be clickable**, but it must live in the footer/chrome
+   and never overlap slide content.
+5. **Expose `window.deckGoto(index)`** (0-based) right after the slide-show
+   function, so review/overlay tools can jump to a slide without simulating clicks
+   or keys:
+
+        function go(n) { /* ...show slide n... */ }
+        window.deckGoto = go;
+
+6. **Keep the hint honest** — the on-screen nav hint should read `← → to navigate`
+   (don't advertise click/space).
+7. **Use stable structural hooks.** Make each slide one element with class
+   `.slide`, and put the slide-number label (if any) in a `.slide-num` element.
+   The review overlay defaults to these selectors to detect and index slides.
+
+These rules keep decks compatible with the **`deck-review`** skill, which installs
+the `slide-annotator.js` review overlay (highlight text on a slide → sidecar JSON
+of feedback that an agent acts on). After producing an interactive HTML deck, you
+can offer to run `deck-review` to make it reviewable; see that skill for the
+install steps and the sidecar JSON schema.
+
 ## Constraints
 
 - Always use the knowledge base for context when available
 - Output to `~/Desktop/presentation.pdf` unless user specifies otherwise
 - Keep slides clean and readable — max 5-6 bullet points per slide
 - Use consistent styling throughout
+- For interactive HTML decks, follow the navigation & event standards above
+  (arrow-keys-only; no click-to-advance or spacebar)

package/templates/.claude/skills/deck-review/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: deck-review
+description: Add a lightweight text-highlight review overlay to an HTML deck. Lets you highlight text on slides and capture feedback as a sidecar JSON (with source line/column + context) that an agent can act on in small iterations. Use when the user asks to add review/annotation/highlight/comment capability to a deck, make a deck "reviewable", or wants to mark up slides for revision. Pairs with the deck-create skill.
+compatibility: Standalone HTML deck opened in a Chromium-based browser (Chrome/Edge). No build step, no server, no dependencies.
+---
+
+# Add a Review Overlay to a Deck
+
+Install the self-contained `slide-annotator.js` overlay onto an HTML deck so the
+user can **highlight text on a slide and save the feedback as a sidecar JSON**.
+Each annotation carries a robust anchor (exact text + surrounding context + slide)
+and, once the folder is connected, the resolved **source line, column and context
+lines** — so an agent can locate and edit the exact text in small iterations.
+
+This is the companion to **`deck-create`**: decks produced by `deck-create`
+already follow the navigation/structure standards this overlay needs, and this
+overlay is designed to drop onto them with one script tag.
+
+## Trigger
+
+Run when the user asks to add review / annotation / highlight / comment / markup
+capability to a deck, "make this deck reviewable", or to set up a feedback loop on
+slides.
+
+## Inputs
+
+- Path to the target deck `.html` file (ask, or default to the most recently
+  edited `*.html` in `Drafts/`).
+- The bundled tool at `assets/slide-annotator.js` (this skill's own copy is the
+  source of truth — edit it here, then re-install to update decks).
+
+## Outputs
+
+- `slide-annotator.js` copied next to the deck.
+- One `<script>` tag injected into the deck before `</body>`.
+- At review time, a sidecar `‹deck›.annotations.json` written next to the deck.
+
+---
+
+## Install steps
+
+1. **Resolve the deck path** (absolute). Confirm it is an HTML deck, not a PDF.
+
+2. **Check compatibility** (see *Compatibility contract* below). The two things
+   that matter:
+   - **Slide selector** — each slide is one element with a stable class
+     (default `.slide`). If the deck uses a different class, note it for step 4.
+   - **Navigation hook** — the deck exposes `window.deckGoto(index)` (0-based).
+     If it has a slideshow function (e.g. `go(n)`) but no hook, add one line right
+     after it: `window.deckGoto = go;`. Without it the overlay still works (the
+     panel's *Go* button falls back to `scrollIntoView`), but it can't jump to a
+     hidden slide precisely.
+   - Optionally a slide-number label element (default `.slide-num`) for nicer
+     labels in the panel — purely cosmetic.
+
+3. **Install the tool**: copy this skill's `assets/slide-annotator.js` into the
+   **same directory as the deck**. Resolve `~` to `$HOME`; pass the Write/copy a
+   full path.
+
+4. **Inject the script tag** immediately before `</body>` (idempotent — skip if a
+   `slide-annotator` script tag is already present):
+
+   ```html
+   <!-- Review overlay: highlight text on a slide → sidecar JSON. Self-contained, optional. -->
+   <script src="slide-annotator.js" defer
+           data-slide-selector=".slide"
+           data-label-selector=".slide-num"></script>
+   ```
+
+   Set `data-slide-selector` / `data-label-selector` to match the deck if it
+   differs from the defaults. If there are no slide elements at all, the tool
+   treats the whole `<body>` as one container.
+
+5. **Tell the user how to use it** (see *Using the overlay*). Do **not** add any
+   other dependency or framework — the tool is plain JS and must stay that way.
+
+## Compatibility contract (must match `deck-create`)
+
+The overlay relies only on these conventions, which `deck-create` decks already
+follow:
+
+| Convention | Default | Why the overlay needs it |
+|---|---|---|
+| One element per slide with a stable class | `.slide` | locate which slide a highlight is on; index slides |
+| Slide-number label element (optional) | `.slide-num` | human-friendly panel labels |
+| Navigation hook | `window.deckGoto(index)` (0-based) | panel "Go" jumps to the right slide |
+| Arrow-keys-only navigation, **no** click-to-advance / spacebar | — | text selection + typing in the overlay must not move slides |
+
+If a deck violates the last row (has click-to-advance), the overlay's click guard
+only suppresses the click that ends a text-selection drag, so it degrades
+gracefully — but the correct fix is to make the deck arrow-keys-only per
+`deck-create`'s *Navigation & Event Standards*.
+
+## Using the overlay (tell the user)
+
+1. Open the deck in Chrome and click **✎ Review** (bottom-left).
+2. **Select text** on a slide → a popover lets you add an optional note → **Add**.
+   The highlight appears and **autosaves to `localStorage`** immediately.
+3. Click **Connect folder** once and pick the deck's folder. From then on **Save**
+   writes a real `‹deck›.annotations.json` next to the deck, and the tool reads the
+   deck's own source to fill in **source line / column / context** for each
+   highlight. (If the browser blocks folder access on `file://`, **Save**
+   downloads the JSON instead — move it next to the deck.)
+4. Navigation while reviewing is the deck's normal **← / →** (the overlay's own
+   keystrokes never leak to the deck).
+
+## Acting on the feedback (the review loop)
+
+When the user says "work the annotations":
+
+1. Read `‹deck›.annotations.json` next to the deck.
+2. For each `status: "open"` annotation, locate the text in the deck source:
+   - Prefer `source.line` / `source.column` when present.
+   - Otherwise search the source for `quote` (disambiguate with `prefix` /
+     `suffix`, scoped to `slideId`). The quote is the underlying DOM text, so it
+     matches the source even across inline tags / entities.
+3. Make the edit, honoring the user's `note`.
+4. Optionally set the annotation's `status` to `"done"` in the JSON so the panel
+   shows it resolved.
+5. Re-render / re-screenshot to verify, then report what changed per annotation.
+
+### Sidecar JSON schema
+
+```jsonc
+{
+  "version": 1, "tool": "slide-annotator",
+  "target": "‹deck›.html", "updatedAt": "‹iso›",
+  "annotations": [{
+    "id", "createdAt", "status": "open" | "done", "note",
+    "slideId", "slideIndex", "slideLabel", "slideTitle",
+    "quote",                       // exact highlighted text (the anchor)
+    "prefix", "suffix",            // ~60 rendered chars either side
+    "renderedStart", "renderedEnd",// char offsets within the slide's text
+    "domPath",                     // CSS-ish path to the containing element
+    "source": {                    // best-effort; null until folder connected
+      "file", "line", "column",
+      "match": "exact" | "normalized" | "none",
+      "contextBefore": [".."], "contextLine": "..", "contextAfter": [".."]
+    }
+  }]
+}
+```
+
+## Removing the overlay (for final delivery)
+
+To hand off a clean presentation, delete the injected `<script src="slide-annotator.js" …>`
+line and the `slide-annotator.js` file. Leaving the `window.deckGoto = go;` line in
+the deck is harmless.
+
+## Constraints
+
+- Keep `slide-annotator.js` **dependency-free and host-agnostic** — it must work
+  on any static HTML page, not just `deck-create` output.
+- Edit the tool **here** (`assets/slide-annotator.js`) as the source of truth, then
+  re-install onto decks. Don't fork per-deck copies with divergent behavior.
+- Never auto-send or upload annotations anywhere — the sidecar JSON stays local.