SOMA AI Footprint

About

# AI Extension — Publishing & Go-Live Checklist

Everything left to make the AI Extension fully distributable to non-technical employees.
The product already works end-to-end via an **unpacked** install (proven in testing); these
steps make it installable from the browser stores and finish the desktop-agent distribution.

Do them in order. Steps 0–1 are required before any store submission.

---

## Step 0 — Verify the web detectors on the LIVE sites (DO THIS FIRST)

The 5 content-script selectors are unit-tested against fixture HTML, **not** the live pages, and
AI sites change their markup often. Confirm each one actually counts usage before you publish.

1. In Chrome: `chrome://extensions` → toggle **Developer mode** (top-right).
2. Click **Load unpacked** → select `extension/dist`.
3. Click the extension icon → it should say **"Not set up yet."**
4. In SOMA, open a client → **Connectors** → AI Extension card → **⋯ → Copy enroll link** →
   paste it in a tab. The page should flip to **"✓ You're all set"** and the popup to **"✓ Active."**
5. For **each** of `chatgpt.com`, `claude.ai`, `gemini.google.com`, `copilot.microsoft.com`,
   `perplexity.ai`: open it logged-in, send 2–3 messages.
6. Open the extension's **service worker** console (`chrome://extensions` → the extension →
   "service worker") and run:
   ```js
   chrome.storage.local.get('ai_buckets').then(console.log)   // should show buckets per site
   somaFlushNow()                                             // force a send → resolves true
   ```
7. Reload the SOMA Connectors page → the **"Staged so far"** line should grow.

**If a site shows nothing**, its selector drifted. Fix the one file
`extension/src/detectors/<site>.ts` (the `userSelector` / `assistantSelector`), `npm run build`,
reload the unpacked extension, retest. (Inspect the page with DevTools to find the new selector.)

---

## Step 1 — Store assets you'll need (have these ready)

- **Icon:** `extension/dist/icon128.png` (128×128) — already generated. Use the same file as the
  Web Store "store icon".
- **Screenshots:** at least 1, **1280×800** or 640×400 PNG. Easiest: a screenshot of the AI
  Extension connector card + the popup. (Chrome requires ≥1; Edge/Firefox similar.)
- **Descriptions:**
  - *Short* (≤132 chars): "Measure your team's AI usage footprint. Counts usage only — never reads what you type. Anonymous."
  - *Detailed:* see the listing copy in `## Appendix A` below.
- **Privacy policy URL:** `https://app.somaai.earth/privacy` — but first add the extension section
  (see `## Step 5`). Chrome **requires** this for any data-handling extension.
- **Category:** Productivity (Chrome/Edge) / "Other" or "Privacy & Security" (Firefox).

---

## Step 2 — Chrome Web Store (covers Chrome **and** Edge users who allow CWS)

1. Zip the build contents (the files, not the parent folder):
   ```bash
   cd extension/dist && zip -r ../soma-ai-chrome.zip . && cd ../..
   ```
2. Go to **https://chrome.google.com/webstore/devconsole** and sign in with the Google account
   you want to own the listing.
3. First time only: pay the **one-time $5** developer registration fee.
4. Click **+ New item** → upload `soma-ai-chrome.zip`.
5. **Store listing** tab: name ("SOMA AI Footprint"), short + detailed description, category
   (Productivity), language, upload the 128 icon and ≥1 screenshot.
6. **Privacy practices** tab:
   - *Single purpose:* "Measure the user's AI usage (message/token counts) to estimate their
     organization's environmental footprint."
   - *Permission justifications:* `storage` (save the anonymous device id + daily counts),
     `alarms`/`idle` (batch the daily upload), host permissions (read message lengths on the 5 AI
     sites — counts only).
   - *Data usage:* declare you collect **"Website content"** in the limited sense of message
     *lengths/counts* (no content stored/sold), and check "data is not sold", "used only for the
     single purpose".
   - Paste the **privacy policy URL**.
7. Click **Submit for review**. Review typically takes a few days.
8. **After approval:** copy the **extension ID** (the 32-char string in the item's dashboard URL
   and the public listing URL `chromewebstore.google.com/detail/<name>/<ID>`). You need it for Step 4.

> Edge: most Edge users can install from the Chrome Web Store directly. For a native Edge listing,
> do Step 3.

---

## Step 3 — Microsoft Edge Add-ons (optional native listing)

1. Go to **https://partner.microsoft.com/dashboard/microsoftedge/overview** and register
   (free; Microsoft Partner Center account).
2. **+ New extension** → upload the **same** `soma-ai-chrome.zip` (Edge uses the Chrome build).
3. Fill listing (reuse the Chrome copy + assets) → **Publish**. Review is usually quick.

---

## Step 4 — Update the extension ID in SOMA, then redeploy

Two placeholders reference the not-yet-known Chrome extension ID. After Step 2 approval:

1. `src/pages/EnrollAi.tsx` → set `CHROME_STORE_URL` to your real listing URL
   (`https://chromewebstore.google.com/detail/<name>/<ID>`).
2. `src/components/connectors/AiExtensionPanel.tsx` → set `CHROME_EXT_ID` to the real **ID**
   (used by the IT managed-deploy policy).
3. Commit + deploy: `git push origin main` (or `vercel --prod --force --yes --archive=tgz`).

No extension rebuild is needed for the ID — Chrome assigns it; only the SOMA app references it.

---

## Step 5 — Privacy policy (required by Chrome)

Add the **Appendix B** text to the `/privacy` page (`src/pages/PrivacyPolicy.tsx`) as a
"SOMA AI Footprint browser extension" section, then redeploy. (Ask Claude to wire it in if you want.)

---

## Step 6 — Firefox Add-ons (AMO)

1. Zip the Firefox build:
   ```bash
   cd extension/dist-firefox && zip -r ../soma-ai-firefox.zip . && cd ../..
   ```
2. Go to **https://addons.mozilla.org/developers/** → sign in with a Firefox account.
3. **Submit a New Add-on** → "On this site" → upload `soma-ai-firefox.zip`.
4. **Source code:** AMO requires source for bundled/minified code. Provide the `extension/` source
   (everything except `node_modules/`, `dist/`, `dist-firefox/`) as a zip when prompted, with build
   steps: `npm install && npm run build` (output in `dist-firefox/`).
5. Fill listing (reuse copy/assets) → submit. Review can take longer than Chrome.

---

## Step 7 — Distribute the desktop agent (for Claude Code / Codex / CLI coverage)

The agent is a Node CLI; pick one:

- **Simplest:** zip `desktop-agent/dist/cli.js` (+ the README) and share with engineers. They run
  `node cli.js enroll <token>` then schedule `node cli.js sync` daily (cron / Task Scheduler).
- **Nicer:** publish to npm so they run `npx soma-ai-tracker enroll <token>`:
  ```bash
  cd desktop-agent
  # set "private": false and a unique public name in package.json, then:
  npm login && npm publish --access public
  ```
- **Zero-touch (IT):** use the connector card's **⋯ → Managed deploy (IT)** dialog — it generates
  the agent config drop (`~/.soma-ai/config.json` with just the token) for IT to place alongside a
  scheduled `sync`.

---

## Step 8 — Enterprise zero-touch for the extension (optional, per client)

For clients with Google Workspace / Intune / Jamf: the connector card's **⋯ → Managed deploy (IT)**
dialog generates the Chrome Enterprise policy (force-install + `enroll_token`). After Step 2/4 the
policy already has the right extension ID. IT pushes it once → every machine auto-enrols, no clicks.

---

## After all steps: it's fully functional

- Web usage (5 platforms) → measured via the published extension, one-click install for employees.
- Desktop/CLI (Claude Code, Codex; Gemini/Copilot after `enable-telemetry`) → desktop agent.
- Un-enrolled staff + desktop chat apps (Claude/ChatGPT app) → seat-based estimate (by design;
  those can't be measured locally — see the feasibility research).
- Consultant: invite from the connector card or the AI page, review → promote to the certified ledger.

---

## Appendix A — Store listing (detailed description)

> **SOMA AI Footprint** measures your organization's environmental footprint from AI tools.
>
> Once your company sets it up, the extension counts your AI usage on ChatGPT, Claude, Gemini,
> Microsoft Copilot and Perplexity and turns it into a carbon and water estimate for your
> company's sustainability report.
>
> • **Private by design** — it only counts usage (message and token *lengths*). It never reads,
>   stores, or transmits what you type or the replies you receive.
> • **Anonymous** — your usage is attributed to your organization with a random device id, not
>   to you personally.
> • **Zero effort** — install once and it runs automatically; nothing else to do.
>
> Part of the SOMA ESG platform used by sustainability consultants. Learn more at somaai.earth.

## Appendix B — Privacy policy section (paste into /privacy)

> **SOMA AI Footprint browser extension**
>
> The SOMA AI Footprint extension is an optional tool deployed by your organization to estimate the
> environmental footprint of its AI usage.
>
> *What it collects:* the number of messages you send and an estimate of the token *lengths* of
> those messages and their replies, on supported AI websites (ChatGPT, Claude, Gemini, Microsoft
> Copilot, Perplexity), aggregated by day, tool, and model.
>
> *What it does NOT collect:* it never reads, stores, or transmits the content of your prompts or
> the AI's responses, your name, email, IP address, or browsing history outside those sites.
>
> *Identification:* usage is associated with your organization via a random device identifier. It
> is not linked to your identity.
>
> *Where it goes:* aggregated counts are sent to SOMA's servers, where they are converted to a
> CO₂e/water estimate and made available to your organization's sustainability consultant. Data is
> not sold or used for advertising.
>
> *Removal:* you can remove the extension at any time from your browser; your organization's
> administrator can also revoke the enrollment link.