From 5b4918d2af37ad7499329dd47506812001458de3 Mon Sep 17 00:00:00 2001
From: beantownbabe <156287695+beantownbabe@users.noreply.github.com>
Date: Mon, 17 Aug 2026 13:35:55 +0200
Subject: [PATCH] Document the Opportunities module and list it as a fifth
 branch
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- opportunities/README.md: what's in the folder, how to update the
  OPPORTUNITIES/SCOUT_RESULTS data, and the fetch-based loading
  architecture (why it's separate from the index.html monolith and
  what that means for anyone editing it)
- Root README.md was still describing four branches with no mention
  of Opportunities at all — added it as the fifth

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 README.md               |  3 +-
 opportunities/README.md | 67 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 69 insertions(+), 1 deletion(-)
 create mode 100644 opportunities/README.md

diff --git a/README.md b/README.md
index c2b5b60..dd60992 100644
--- a/README.md
+++ b/README.md
@@ -1,10 +1,11 @@
 # TXproducts Sales & Marketing Department
 
-Home for the department, organized into four branches:
+Home for the department, organized into five branches:
 
 - **Team** — who's on marketing/sales and their roles. See `team/`.
 - **Directory (Outreach Board)** — unified outreach tracking across all lead sources. See `address_book/`.
 - **Marketing → Social Media** — currently just LinkedIn. Lives at `~/Documents/linkedin_analytics/` (not yet moved here).
 - **Sales → Intelligence Board** — market/competitor research feeding pitch angles and outreach hesitations. Lives at `~/Documents/market-intelligence/` (not yet moved here).
+- **Opportunities** — conferences/events TXproducts is tracking, plus Conference Scout, a scheduled agent that finds new candidates weekly. See `opportunities/` and `agents/conference-scout/`.
 
 `linkedin_analytics/` and `market-intelligence/` stay at their current paths for now — `linkedin_analytics` runs as a `launchd` background service tied to its current absolute path, so it needs its plist updated before it can move safely. This folder is the skeleton the rest of the department will grow into.
diff --git a/opportunities/README.md b/opportunities/README.md
new file mode 100644
index 0000000..8483478
--- /dev/null
+++ b/opportunities/README.md
@@ -0,0 +1,67 @@
+# Opportunities
+
+Tracks conferences and events worth attending or watching, plus Conference
+Scout, a scheduled agent that finds new candidates automatically. Lives in
+the Sales & Marketing dash's Opportunities tab (localhost:8500).
+
+## Files
+
+- `opportunities.html` — the tab's markup (Events list + calendar card,
+  Conference Scout drill-view). Fetched and injected into the shell's empty
+  `#tab-opportunities` container at page load — it is not present in
+  `index.html` itself.
+- `opportunities.js` — everything behavioral: the `OPPORTUNITIES` (Events
+  list + calendar) and `SCOUT_RESULTS` (Conference Scout candidates) data
+  arrays, the calendar renderer, event-list renderer, and the drill-view
+  registration that plugs this module into the shared shell (see
+  "Architecture" below). Loaded as a normal `<script src>` right after the
+  HTML above is injected.
+- `opportunities.css` — all styling for both cards and the calendar.
+
+## Updating the data
+
+Both data arrays live as plain JS literals at the top of `opportunities.js`
+— no build step, just edit and reload the page.
+
+- **`OPPORTUNITIES`** — confirmed events TXproducts is tracking or attending.
+  One entry per event: `{ start, end (optional, defaults to start), title,
+  location, attendee (optional), url (optional), abstract (optional) }`.
+  Dates are `"YYYY-MM-DD"`. Multi-day entries render as a single bar
+  spanning their date range on the calendar.
+- **`SCOUT_RESULTS`** — this week's Conference Scout candidates, hand-copied
+  in from the routine's latest run (see `agents/conference-scout/`). Each
+  entry: `{ title, dates (display text, not parsed), location, url
+  (optional), reason }`. This list is fully replaced on each sync, not
+  accumulated — it's a snapshot of the latest run, not a running history.
+
+There is currently no automated sync between a Conference Scout run
+finishing and this array being updated — see
+[`agents/conference-scout/README.md`](../agents/conference-scout/README.md)
+for why, and what the actual weekly workflow looks like.
+
+## Architecture: why this is fetched instead of inline
+
+Every other tab in this dash (Team, Directory, Marketing, Sales) is still
+authored directly inside `index.html`. Opportunities was pulled out into its
+own module as a first step toward breaking up that monolith, so it uses a
+small loader pattern instead:
+
+```
+index.html:
+  <div id="tab-opportunities" class="tab-content">…</div>   <!-- empty on load -->
+  fetch("opportunities/opportunities.html") → inject as innerHTML
+    → then append <script src="opportunities/opportunities.js">
+```
+
+Two consequences worth knowing if you're editing this:
+
+- **The module registers itself.** `index.html`'s shared `HERO_NAV_BY_TAB`,
+  `DRILL_CONFIG`, and `DRILL_DEFAULT_VIEW` objects do *not* contain an
+  `opportunities` entry — `opportunities.js` adds one at the bottom, once its
+  own HTML exists in the DOM. `setDrillView()` in the shell tolerates a scope
+  that isn't registered yet (it just no-ops), which is what makes the load
+  order safe.
+- **Nothing here runs until the fetch resolves.** For a local static file
+  this is near-instant, so in practice there's no visible delay, but if you
+  ever see the Opportunities tab stuck on "Loading…", check the browser
+  console for a fetch/network error first.