@forwardimpact/outpost 3.9.0 → 3.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardimpact/outpost",
-  "version": "3.9.0",
+  "version": "3.11.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

@@ -2,7 +2,7 @@
  * KBManager — knowledge base init/update operations.
  */
 
-import { join, dirname, resolve } from "node:path";
+import { join, dirname, resolve, basename } from "node:path";
 import { homedir } from "node:os";
 import { createLogger } from "@forwardimpact/libtelemetry";
 
@@ -214,6 +214,7 @@ export class KBManager {
       await this.#ensureDir(join(dest, d));
 
     await this.copyBundledFiles(templateDir, dest);
+    await this.#linkIntoDocuments(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 person-identify skill to populate your identity`,
@@ -221,6 +222,31 @@ export class KBManager {
     return { ok: true, value: { dest } };
   }
 
+  /**
+   * Create a navigation symlink at `~/Documents/<name>` pointing to the KB.
+   * The KB data itself stays under the XDG data home, outside TCC-protected
+   * folders — this is only a convenience pointer so the KB is easy to find and
+   * open from Finder. Best-effort: a pre-existing entry is left untouched, and
+   * any failure (e.g. macOS denying write access to `~/Documents`) is logged,
+   * never fatal, because the KB is already provisioned at `dest`.
+   * @param {string} dest - Absolute path to the provisioned KB.
+   * @returns {Promise<void>}
+   */
+  async #linkIntoDocuments(dest) {
+    const link = join(homedir(), "Documents", basename(dest));
+    if (await this.#exists(link)) {
+      this.#logger.info(`  Skipped ${link}: already exists`);
+      return;
+    }
+    try {
+      await this.#ensureDir(dirname(link));
+      await this.#fs.symlink(dest, link, "dir");
+      this.#logger.info(`  Linked ${link} -> ${dest}`);
+    } catch (err) {
+      this.#logger.info(`  Could not link into ~/Documents: ${err.message}`);
+    }
+  }
+
   /**
    * Update an existing knowledge base with the latest bundled files.
    * @param {string} targetPath

package/templates/.claude/agents/chief-of-staff.md

@@ -14,16 +14,18 @@ single briefing.
 
 ## Priorities
 
-`Knowledge/Priorities/` is the backbone of every briefing. Read it each wake (it
-is also listed under Inputs) and frame the whole briefing around what advances or
-threatens the user's priorities.
+`Knowledge/Priorities/` is the backbone of every briefing. Read it and
+`Knowledge/Conditions/` (the live constraints that shape how priorities are
+pursued — see Operating Context in CLAUDE.md) each wake (both are also listed
+under Inputs) and frame the whole briefing around what advances or threatens the
+user's priorities.
 
 - **Always consider them.** Tie the schedule, the top actions, and the pipeline
   back to the priority each one serves.
 - **Always escalate risks.** Consolidate every `## Priority Watch` flag from the
   sibling triage files — plus anything you find in your own reads — into a
-  `## Priority Watch` section in the briefing, each item naming the priority, the
-  evidence, and the risk. A signal that could contradict, block, or slow a
+  `## Priority Watch` section in the briefing, each item naming the priority,
+  the evidence, and the risk. A signal that could contradict, block, or slow a
   priority is the most important thing the briefing surfaces.
 
 ## Inputs
@@ -37,7 +39,7 @@ authoritative current-state summaries:
 - `~/.cache/fit/outpost/state/recruiter_triage.md`
 - `~/.cache/fit/outpost/state/head_hunter_triage.md`
 
-Plus directly: `Knowledge/Priorities/`, `Drafts/`,
+Plus directly: `Knowledge/Priorities/`, `Knowledge/Conditions/`, `Drafts/`,
 `~/.cache/fit/outpost/apple_calendar/`, and unchecked `- [ ]` items in
 `Knowledge/`.
 
@@ -64,7 +66,7 @@ and "Still Outstanding".
 
 ## Output
 
-```
+```text
 Decision: {morning/evening} briefing — {key insight about today}
 Action: Created Briefings/{YYYY-MM-DD}-{morning|evening}.md
 ```

package/templates/.claude/agents/concierge.md

@@ -18,11 +18,13 @@ recordings.
 
 ## Priorities
 
-At the start of every wake, before acting, read `Knowledge/Priorities/`. The
-user's priorities are the lens for all your work this wake.
+At the start of every wake, before acting, read `Knowledge/Priorities/` and
+`Knowledge/Conditions/` (which constrains them — see Operating Context in
+CLAUDE.md). The user's priorities are the lens for all your work this wake.
 
 - **Always consider them.** Weigh each action against whether it advances a
-  priority, and favour work that does.
+  priority, and favour work that does. Let the active conditions shape how you
+  act on it.
 - **Always flag risks.** When you encounter a chat, email, transcript, or any
   other signal that could **contradict, block, or slow** a priority, record it
   under a `## Priority Watch` heading in your triage report — name the priority,
@@ -53,7 +55,7 @@ over **anarlog-process** (catch-up work).
 
 After acting, emit exactly:
 
-```
+```text
 Decision: {what you observed and why you chose this action}
 Action: {what you did, e.g. "meeting-prep for 2pm with Sarah Chen"}
 Priority Watch: {priority at risk + one-line why, or "none"}

package/templates/.claude/agents/head-hunter.md

@@ -21,11 +21,13 @@ benchmark promising matches, and write prospect notes for the user to review.
 
 ## Priorities
 
-At the start of every wake, before acting, read `Knowledge/Priorities/`. The
-user's priorities are the lens for all your work this wake.
+At the start of every wake, before acting, read `Knowledge/Priorities/` and
+`Knowledge/Conditions/` (which constrains them — see Operating Context in
+CLAUDE.md). The user's priorities are the lens for all your work this wake.
 
 - **Always consider them.** Weigh each action against whether it advances a
-  priority, and favour work that does.
+  priority, and favour work that does. Let the active conditions shape how you
+  act on it.
 - **Always flag risks.** When you encounter a chat, email, transcript, or any
   other signal that could **contradict, block, or slow** a priority, record it
   under a `## Priority Watch` heading in your triage report — name the priority,
@@ -63,7 +65,7 @@ wake — the chief-of-staff reads it.
 
 ## Output
 
-```
+```text
 Decision: {source chosen and why}
 Action: {what was scanned, e.g. "scanned HN Who Wants to Be Hired March 2026, 47 posts"}
 Prospects: {N} new ({strong} strong, {moderate} moderate), {total} total

package/templates/.claude/agents/librarian.md

@@ -16,11 +16,13 @@ you process new data into the knowledge graph and keep everything organized.
 
 ## Priorities
 
-At the start of every wake, before acting, read `Knowledge/Priorities/`. The
-user's priorities are the lens for all your work this wake.
+At the start of every wake, before acting, read `Knowledge/Priorities/` and
+`Knowledge/Conditions/` (which constrains them — see Operating Context in
+CLAUDE.md). The user's priorities are the lens for all your work this wake.
 
 - **Always consider them.** Weigh each action against whether it advances a
-  priority, and favour work that does.
+  priority, and favour work that does. Let the active conditions shape how you
+  act on it.
 - **Always flag risks.** When you encounter a chat, email, transcript, or any
   other signal that could **contradict, block, or slow** a priority, record it
   under a `## Priority Watch` heading in your triage report — name the priority,
@@ -31,18 +33,20 @@ user's priorities are the lens for all your work this wake.
 
 Assess what needs processing:
 
-1.  Check for unprocessed synced files (mail and calendar data):
+1. Check for unprocessed synced files (mail and calendar data):
 
-        node .claude/skills/extract-entities/scripts/state.mjs check
+   ```text
+    node .claude/skills/extract-entities/scripts/state.mjs check
+   ```
 
-2.  Count existing knowledge graph entities:
+2. Count existing knowledge graph entities:
 
-    ls Knowledge/People/ Knowledge/Organizations/ Knowledge/Projects/
-    Knowledge/Topics/ Knowledge/Priorities/ 2>/dev/null | wc -l
+   ls Knowledge/People/ Knowledge/Organizations/ Knowledge/Projects/
+   Knowledge/Topics/ Knowledge/Priorities/ 2>/dev/null | wc -l
 
 Write triage results to `~/.cache/fit/outpost/state/librarian_triage.md`:
 
-```
+```text
 # Knowledge Triage — {YYYY-MM-DD HH:MM}
 ## Pending Processing
 - {count} unprocessed synced files
@@ -64,7 +68,7 @@ Choose the most valuable action:
 
 After acting, output exactly:
 
-```
+```text
 Decision: {what you observed and why you chose this action}
 Action: {what you did, e.g. "extract-entities on 7 files"}
 Priority Watch: {priority at risk + one-line why, or "none"}

package/templates/.claude/agents/postman.md

@@ -17,11 +17,13 @@ and Teams, triage what's new, take the most valuable action.
 
 ## Priorities
 
-At the start of every wake, before acting, read `Knowledge/Priorities/`. The
-user's priorities are the lens for all your work this wake.
+At the start of every wake, before acting, read `Knowledge/Priorities/` and
+`Knowledge/Conditions/` (which constrains them — see Operating Context in
+CLAUDE.md). The user's priorities are the lens for all your work this wake.
 
 - **Always consider them.** Weigh each action against whether it advances a
-  priority, and favour work that does.
+  priority, and favour work that does. Let the active conditions shape how you
+  act on it.
 - **Always flag risks.** When you encounter a chat, email, transcript, or any
   other signal that could **contradict, block, or slow** a priority, record it
   under a `## Priority Watch` heading in your triage report — name the priority,
@@ -54,7 +56,7 @@ email only.
 
 After acting, emit exactly:
 
-```
+```text
 Decision: {what you observed and why you chose this action}
 Action: {what you did, e.g. "draft-emails for thread 123"}
 Priority Watch: {priority at risk + one-line why, or "none"}

package/templates/.claude/agents/recruiter.md

@@ -22,11 +22,13 @@ assessment and recommendation references the standard.
 
 ## Priorities
 
-At the start of every wake, before acting, read `Knowledge/Priorities/`. The
-user's priorities are the lens for all your work this wake.
+At the start of every wake, before acting, read `Knowledge/Priorities/` and
+`Knowledge/Conditions/` (which constrains them — see Operating Context in
+CLAUDE.md). The user's priorities are the lens for all your work this wake.
 
 - **Always consider them.** Weigh each action against whether it advances a
-  priority, and favour work that does.
+  priority, and favour work that does. Let the active conditions shape how you
+  act on it.
 - **Always flag risks.** When you encounter a chat, email, transcript, or any
   other signal that could **contradict, block, or slow** a priority, record it
   under a `## Priority Watch` heading in your triage report — name the priority,
@@ -60,11 +62,12 @@ screen > sync. Stage 3 **never** triggers automatically — only on user request
 
 Triage state goes to `~/.cache/fit/outpost/state/recruiter_triage.md` every wake
 (the chief-of-staff reads it): needs-action by stage, recently processed
-candidates, pipeline totals by stage/track, aggregate diversity, retention flags.
+candidates, pipeline totals by stage/track, aggregate diversity, retention
+flags.
 
 ## Output
 
-```
+```text
 Decision: {observation and chosen action}
 Action: {e.g. "req-screen for John Smith against J060 forward-deployed"}
 Stage: {1 | 2 | sync | erasure}

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

@@ -101,8 +101,8 @@ interactions.
 #### 5. Load type-specific context
 
 **Interviews:** read `Knowledge/Candidates/{Name}/{brief,screening,panel}.md`,
-look up the `Req` field's matching `Knowledge/Roles/*.md`, and load standard
-expectations:
+look up the `Req` field's matching `Knowledge/Roles/*.md` file (check the
+`**Status:**` field for context), and load standard expectations:
 
 ```bash
 bunx fit-pathway job {discipline} {level} --track={track}

package/templates/.claude/skills/anarlog-follow/references/coaching.md

@@ -6,7 +6,7 @@ Reference for `anarlog-follow` Phases 2 and 3.
 
 ### For interviews
 
-```
+```text
 Following: {Title}
 Type: {Interview type}
 Candidate: {Name} — {current role} at {employer}
@@ -27,7 +27,7 @@ Watching for: {specific signals at this interview stage}
 
 ### For general meetings
 
-```
+```text
 Following: {Title}
 Attendees: {names with roles}
 
@@ -66,7 +66,7 @@ Suggested topics:
 
 Output **only when actionable**. Each nudge: 1–3 lines max.
 
-```
+```text
 Probe deeper: {Name} mentioned {topic} — ask for a specific example
 Gap: screening flagged {skill} as uncertain. Try: "{question}"
 Confirmed: {Name} demonstrated {skill} at {level} — "{brief quote}"

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

@@ -46,9 +46,11 @@ Run this skill:
 ### Step 0 — Validate the session
 
 1. Confirm the session directory exists:
-   ```
+
+   ```text
    ~/Library/Application Support/anarlog/sessions/{uuid}/
    ```
+
 2. Confirm `transcript.json` exists and has at least one transcript with words.
 3. Read `_meta.json` to get the session title for context.
 
@@ -132,7 +134,8 @@ json.dump(data, open(path, 'w'), indent=2)
 ```
 
 4. Print a summary:
-   ```
+
+   ```text
    Trimmed: {title}
      Before: {original_words} words, {original_duration}
      After:  {new_words} words, {new_duration}
@@ -147,11 +150,14 @@ people who did not consent to being recorded. The full audio file must be
 deleted to respect participant privacy.
 
 1. Delete the audio file:
+
    ```bash
    rm "~/Library/Application Support/anarlog/sessions/{uuid}/audio.mp3"
    ```
+
 2. Confirm deletion and inform the user:
-   ```
+
+   ```text
    Audio deleted: audio.mp3 removed (recording contained unconsented content beyond the meeting)
    ```
 

package/templates/.claude/skills/candidate-report/SKILL.md

@@ -50,7 +50,8 @@ before deciding whether to invest interview time.
 - [ ] Verdict class matches the overall assessment.
 - [ ] Report fits on a single A4 page (browser print preview).
 - [ ] CSS is inlined in the `<style>` block.
-- [ ] Footer shows the author name and role from `~/.cache/fit/outpost/state/identity.md`.
+- [ ] Footer shows the author name and role from
+      `~/.cache/fit/outpost/state/identity.md`.
 - [ ] Written as if the candidate will read it; no special-category data.
 
 </do_confirm_checklist>
@@ -61,7 +62,7 @@ before deciding whether to invest interview time.
 
 Read whatever exists for the candidate:
 
-```
+```text
 Knowledge/Candidates/{Name}/brief.md        # required
 Knowledge/Candidates/{Name}/screening.md    # if produced by req-screen
 Knowledge/Candidates/{Name}/interview-*.md  # if produced by req-assess
@@ -118,7 +119,7 @@ preview overflows, cut content.
 
 Save the completed HTML to:
 
-```
+```text
 Drafts/{Recipient}-{CandidateSurname}-Report.html
 ```
 

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

@@ -11,8 +11,8 @@ 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.
+other subdirectories. It does **not** track changes to instructions
+(`CLAUDE.md`, agents, skills) — that is the `upstream-instructions` skill's job.
 
 ## Trigger
 
@@ -40,16 +40,16 @@ agents, skills) — that is the `upstream-instructions` skill's job.
 
 ## 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.
+`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.
+- [ ] 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.
@@ -104,8 +104,8 @@ 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:
+Create or update `Knowledge/CHANGELOG.md` (newest first). Group entries under
+one heading per day; one bullet per logical change:
 
 ```markdown
 # Knowledge Changelog

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

@@ -32,18 +32,18 @@ Run when the user asks to create a presentation, slide deck, or pitch deck.
 
 ## Workflow
 
-1.  Check `Knowledge/` for relevant context about the company, product, team,
-    etc.
-2.  Ensure Playwright is installed:
-    `bun install playwright && bunx playwright install chromium`
-3.  Create an HTML file at `/tmp/outpost-presentation.html` with slides
-    (1280x720px each)
-4.  Include the required CSS from [references/slide.css](references/slide.css)
-5.  Run the conversion script:
+1. Check `Knowledge/` for relevant context about the company, product, team,
+   etc.
+2. Ensure Playwright is installed:
+   `bun install playwright && bunx playwright install chromium`
+3. Create an HTML file at `/tmp/outpost-presentation.html` with slides
+   (1280x720px each)
+4. Include the required CSS from [references/slide.css](references/slide.css)
+5. Run the conversion script:
 
         node scripts/convert-to-pdf.mjs
 
-6.  Tell the user: "Your presentation is ready at ~/Desktop/presentation.pdf"
+6. Tell the user: "Your presentation is ready at ~/Desktop/presentation.pdf"
 
 **Do NOT show HTML code to the user. Just create the PDF and deliver it.**
 
@@ -82,28 +82,29 @@ selecting/copying text on a slide, and typing into overlay tools (e.g. the
 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.
+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, 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).
+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.
+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
 

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

@@ -8,9 +8,10 @@ compatibility: Standalone HTML deck opened in a Chromium-based browser (Chrome/E
 
 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.
+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
@@ -19,8 +20,8 @@ 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.
+capability to a deck, "make this deck reviewable", or to set up a feedback loop
+on slides.
 
 ## Inputs
 
@@ -46,10 +47,10 @@ slides.
    - **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.
+     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.
 
@@ -57,8 +58,8 @@ slides.
    **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):
+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. -->
@@ -86,22 +87,30 @@ follow:
 | 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
+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
+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. The connected folder is **remembered across reloads** (the directory handle
+   is stored in IndexedDB, keyed per deck). After a reload the tool reconnects
+   silently if the browser still grants access; otherwise the button reads
+   **Reconnect folder** and a single click re-grants permission without
+   re-picking the folder. (Browsers require a user gesture to re-grant, so the
+   one click can't be avoided; clearing site data forgets the folder.)
+5. 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)
@@ -143,14 +152,15 @@ When the user says "work the annotations":
 
 ## 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.
+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.
+- 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.