# ⚡ Substack Edge Cache — Extension Install Guide

> A lightweight browser extension for Chrome, Brave, Arc, Edge, & Orion that connects to our shared edge cache at [`sbstck.minntelligence.fyi`](https://sbstck.minntelligence.fyi).

---

## 🧐 What Is This?

Whenever you browse to any Substack article (e.g. `*.substack.com/p/...` or custom publication domains), this extension:

1. **Checks the edge cache in the background** — If a cached copy (full article or preview) exists on our Cloudflare network, a dark floating badge pops up:
   > **⚡ Cached on Edge**  
   > *A cached version is available from your shared edge network.*  
   > **[Open Clean Reader]**
2. **1-Click Clean Reader** — Clicking the button opens a clean, typography-focused reader version without paywall popups, trackers, or clutter.
3. **Save & Share for the Group** — If you have access to a post, you can 1-click cache/sync it to the shared edge so everyone in the group can read it.
4. **Archive.is & Wayback Fallbacks** — If a post or news article isn't in our primary database yet, our edge automatically checks `archive.today` / `archive.is` and Wayback snapshots to pull full archived copies on the fly!

---

## 📥 1. Download the Extension

1. Download the packaged extension zip:  
   👉 **[Download sbstck-extension.zip](https://sbstck.minntelligence.fyi/extension.zip)** (or [`https://sbstck.minntelligence.fyi/download`](https://sbstck.minntelligence.fyi/download))
2. **Extract / Unzip** `extension.zip` on your computer.
3. Move the unzipped `extension` folder somewhere safe (e.g. `Documents/sbstck-extension` or `Applications/sbstck-extension`).  
   *(⚠️ Keep this folder where it is — Chrome runs the extension directly from this folder!)*

---

## 💻 2. Install in Your Browser

Works on **Google Chrome, Brave, Arc, Microsoft Edge, Opera, Orion**, or any Chromium-based browser.

### Chrome, Brave, Arc, Edge, & Chromium

1. Open your browser's extension settings page:
   - **Chrome:** Navigate to `chrome://extensions`
   - **Brave:** Navigate to `brave://extensions`
   - **Edge:** Navigate to `edge://extensions`
   - **Arc:** Open `arc://extensions` or click **Arc Menu > Settings > Extensions**
2. In the top-right corner, switch on **"Developer mode"** (toggle switch).
3. In the top-left corner, click the **"Load unpacked"** button.
4. Select the extracted `extension` folder (the folder containing `manifest.json`, `content.js`, `popup.html`, etc.).
5. **That's it!** You should now see **Substack Edge Cache** in your installed extensions list.

### 📌 Pin to Your Toolbar (Recommended)
- Click the puzzle piece icon (🧩) in the top-right of your browser.
- Find **Substack Edge Cache** and click the pin icon (📌) so the icon is always visible.

---

## 🚀 3. How to Use It

### ⚡ 1. Reading Cached Posts (Automatic Badge)
- Browse normally to any Substack article (e.g. `https://example.substack.com/p/my-post`).
- If it's already in our cache, a floating dark widget appears in the bottom right corner:
  > **⚡ Cached on Edge**  
  > *A cached version is available from your shared edge network.*  
  > **[Open Clean Reader]**
- Click **"Open Clean Reader"** to open the clean reader page (`https://sbstck.minntelligence.fyi/read/<hash>`) with full text, images, and formatting.

### 📤 2. Caching a Post for Others
- If you're reading an article that isn't cached yet, or you want to archive a copy for your oomfies:
- Click the **Substack Edge Cache** icon in your browser toolbar.
- The popup will show the cache status. Click **"Cache Post"** (or let it auto-extract from the DOM).
- The article is immediately cleaned, indexed, and stored on the Cloudflare edge cache for the group.

### 🏷️ Status Indicators
- 🟢 **Full copy available:** Complete article text and images are saved on edge.
- 🟡 **Preview copy:** Intro/teaser excerpt only.
- ⚪ **Not cached yet:** Article has not yet been archived on the edge network.

---

## ❓ Frequently Asked Questions (FAQ)

### Q: Does it work on *The New York Times*, *The Washington Post*, or other news sites?
**Yes, via the built-in `archive.is` / `archive.today` fallback!**

- **Native Substack Support:** For all Substacks (`*.substack.com` and custom domains like Astral Codex Ten or Pirate Wires), the extension directly interacts with Substack's API and DOM to instantly extract, clean, and cache posts in 1 click.
- **News Sites (NYT, WaPo, Bloomberg, WSJ, The Atlantic):** Because these sites use hard server-side paywalls, the edge backend queries **`archive.today` / `archive.is`** and **Wayback Machine** snapshots.
- If a snapshot exists in the archive network, our edge will automatically clean, index, and cache it for the clean reader.
- If a brand-new article isn't in archive.today yet, any group member can snapshot it on [archive.today](https://archive.today) (or run the local Playwright archiver script `node scripts/archive-playwright.mjs <url>`), and it will instantly become available on `sbstck.minntelligence.fyi` for everyone!

---

## 🔄 4. Updating the Extension

When a new version or bugfix drops:
1. Download the updated `extension.zip`.
2. Replace the files inside your existing `extension` folder.
3. Go to `chrome://extensions` (or `brave://extensions`) and click the reload icon (🔄) on the **Substack Edge Cache** card.

---

## 🔗 Quick Links

- **Extension Download (.zip):** [`https://sbstck.minntelligence.fyi/extension.zip`](https://sbstck.minntelligence.fyi/extension.zip)
- **Web Guide:** [`https://sbstck.minntelligence.fyi/guide`](https://sbstck.minntelligence.fyi/guide)
- **Raw Markdown Guide:** [`https://sbstck.minntelligence.fyi/guide.md`](https://sbstck.minntelligence.fyi/guide.md)
- **Recent Cached Posts:** [`https://sbstck.minntelligence.fyi/api/recent`](https://sbstck.minntelligence.fyi/api/recent)