# Kade — Slack Bot Install Checklist **For:** Jimmie (admin steps you have to do yourself) **From:** Riv **Date:** 2026-05-22 **Estimated time:** ~15 minutes if you have your Slack admin login handy --- ## What this is Kade lives in Slack. To get him there, a Slack app has to be created and installed in J2's workspace. **This is a one-time setup that requires your workspace admin login** — I can't do it for you, but I can hand you the exact checklist. You'll work in two places: 1. **Slack API dashboard** (https://api.slack.com/apps) — to create the app and copy its tokens 2. **Riv's bot config file** (I'll tell you which file) — to paste the tokens in Don't paste tokens anywhere else. Don't share the screen. Don't message them to me — you'll **save them in the file yourself** and I'll read them locally when I build the bot. --- ## Pre-flight - [ ] You have admin or workspace-owner access to J2's Slack workspace - [ ] You're on a machine where the Kade bot will eventually run (your main Windows PC — same one Atlas runs on) - [ ] You have a moment of uninterrupted time. This is not a "between meetings" task. ~15 min. --- ## Step 1 — Create the Slack app 1. [ ] Open https://api.slack.com/apps in your browser 2. [ ] Click **"Create New App"** (top right) 3. [ ] Choose **"From scratch"** 4. [ ] App Name: **`Kade`** 5. [ ] Pick a workspace: **J2's workspace** (don't pick a personal sandbox) 6. [ ] Click **"Create App"** You should now be on Kade's app settings page. Keep this tab open — you'll come back to it. --- ## Step 2 — Set the bot identity (one-time cosmetic) 1. [ ] In the left sidebar, click **"Basic Information"** (probably already selected) 2. [ ] Scroll to **"Display Information"** section 3. [ ] Short description: **`Personal ops assistant — meds, tasks, reminders. Direct, no-nonsense.`** 4. [ ] Background color: pick something dark-ish (e.g. `#1A1A1A`). Doesn't matter functionally, just so he stands out in DMs. 5. [ ] App icon: upload one if you want. Or skip — placeholder is fine for v0.1. (Pixel can make one later if you care.) 6. [ ] Click **"Save Changes"** at the bottom --- ## Step 3 — Configure bot scopes This tells Slack what Kade is allowed to do. Don't add scopes I don't list here — least-privilege. 1. [ ] In the left sidebar, click **"OAuth & Permissions"** 2. [ ] Scroll to **"Scopes" → "Bot Token Scopes"** 3. [ ] Click **"Add an OAuth Scope"** and add each of these one at a time: **Required for v0.1 (meds-only):** - [ ] `chat:write` — send messages - [ ] `im:history` — read DMs Jimmie sends to Kade - [ ] `im:read` — list DM channels - [ ] `im:write` — open DM channel with Jimmie if it doesn't exist yet - [ ] `users:read` — look up Jimmie's user ID at startup - [ ] `reactions:read` — see when Jimmie 👍s a med reminder (counts as ack) **Required for v0.2+ but cheaper to add now (avoids a re-install later):** - [ ] `files:read` — read voice memos Jimmie drops into DM - [ ] `commands` — slash commands like `/dnd` (v0.3) **Do NOT add these** (over-permission red flags): - ❌ `channels:read` / `channels:history` — Kade should not be able to read team channels - ❌ `users:read.email` — not needed - ❌ Anything ending in `.write` you don't see in my list --- ## Step 4 — Install the app to J2's workspace 1. [ ] Still on **"OAuth & Permissions"** page 2. [ ] Scroll **up** to the top 3. [ ] Click **"Install to [workspace name]"** 4. [ ] Slack will show a permission summary — confirm it matches the scopes you added above 5. [ ] Click **"Allow"** 6. [ ] You'll bounce back to the OAuth page. Now there will be a **"Bot User OAuth Token"** at the top, starting with `xoxb-...` 7. [ ] **Copy this token.** Don't paste it here. Don't message it to me. Hold it for Step 6. --- ## Step 5 — Get the app-level signing secret + app token These are needed for the bot to verify incoming Slack events. **5a. App signing secret:** 1. [ ] Left sidebar → **"Basic Information"** 2. [ ] Scroll to **"App Credentials"** 3. [ ] Find **"Signing Secret"**, click **"Show"** 4. [ ] **Copy this.** Hold it for Step 6. **5b. App-level token (for Socket Mode):** 1. [ ] Same page, scroll down to **"App-Level Tokens"** 2. [ ] Click **"Generate Token and Scopes"** 3. [ ] Token name: **`kade-socket-token`** 4. [ ] Add scope: **`connections:write`** 5. [ ] Click **"Generate"** 6. [ ] Token will be shown ONCE. It starts with `xapp-...`. **Copy it.** Hold for Step 6. --- ## Step 6 — Enable Socket Mode (so the bot can run locally without exposing a public URL) 1. [ ] Left sidebar → **"Socket Mode"** 2. [ ] Toggle **"Enable Socket Mode"** to ON 3. [ ] Slack may ask for the app-level token — paste it (the `xapp-...` one) 4. [ ] Save Why Socket Mode: it means Kade runs entirely on your local machine, no need to set up a public webhook URL. Way simpler for v0.1. --- ## Step 7 — Subscribe to events 1. [ ] Left sidebar → **"Event Subscriptions"** 2. [ ] Toggle **"Enable Events"** to ON 3. [ ] Scroll to **"Subscribe to bot events"** 4. [ ] Add: `message.im` (so Kade sees Jimmie's DMs) 5. [ ] Add: `reaction_added` (so Kade sees 👍 acks) 6. [ ] Click **"Save Changes"** at the bottom --- ## Step 8 — Paste the three secrets into Kade's config file This is the only step where the tokens leave the Slack dashboard. You'll save them in **one** local file that only you can read. 1. [ ] Open this file in any text editor (Notepad++, VS Code, whatever): - **`C:\PKA\Team\Riv\kade_slack\.env`** - (If the file doesn't exist yet, create it. Riv is creating the parent folder and the rest of the bot scaffold today — the `.env` is the one piece only you can fill in.) 2. [ ] Paste exactly this template, then fill in the values you copied: ``` SLACK_BOT_TOKEN=xoxb-...your-token-here... SLACK_SIGNING_SECRET=...your-signing-secret-here... SLACK_APP_TOKEN=xapp-...your-app-token-here... ATLAS_INGEST_TOKEN= KADE_SLACK_USER_ID= TZ=America/Chicago ``` 3. [ ] Save the file 4. [ ] **DM me "Kade .env saved"** when done — don't send the contents, just the confirmation --- ## Step 9 — Confirm by checking the Slack app dashboard (not by re-reporting to me) Before you DM me, take 30 seconds to verify in the Slack dashboard: - [ ] Kade is installed in J2's workspace (Basic Information page shows "Installed") - [ ] Bot scopes match my list (OAuth & Permissions → Bot Token Scopes) - [ ] Socket Mode is ON (Socket Mode page, toggle green) - [ ] Events are subscribed: `message.im` and `reaction_added` (Event Subscriptions page) If anything's off, fix it in the dashboard and don't tell me — I'll see it on my end when I try to start the bot. If you can't figure something out, **screenshot the page and DM me the screenshot**, don't try to type out what you see. --- ## What I do next (after you DM me "Kade .env saved") 1. I bring up the bot scaffold pointing at your `.env` 2. First run: bot connects to Slack, opens a DM with you, sends: > "Kade online. Confirm med times: > - Adderall morning — 8:00am? > - Adderall midday — 11:45am ✅ > - Adderall afternoon — 3:00pm? > - Buspar — 8:00am? > - Metformin — 5:30pm ✅ > Reply with corrections." 3. You reply with corrections (or "all good") 4. I update `kade_meds.fire_local_time` directly in Atlas DB 5. Meds fire on the real schedule starting next morning --- ## Estimated time per step | Step | Time | |---|---| | 1. Create app | 2 min | | 2. Identity | 2 min | | 3. Scopes | 3 min | | 4. Install | 1 min | | 5. Tokens | 2 min | | 6. Socket Mode | 1 min | | 7. Events | 1 min | | 8. .env paste | 2 min | | 9. Verify | 1 min | | **Total** | **~15 min** | --- ## If you get stuck Three failure modes I see often: 1. **"Install to workspace" is greyed out** → You're not a workspace admin. Check with whoever is. (Probably you, but worth flagging if not.) 2. **App token doesn't show after generating** → Slack only shows app-level tokens once. If you missed it, hit "Generate Token and Scopes" again and make a new one. 3. **"Socket Mode" toggle disabled** → You need the app-level token (Step 5b) created first. Generate it, then come back. If something else breaks, screenshot the page and DM me. Don't try to describe it in words — Slack's UI changes occasionally and I'd rather see what you see.