context-bridge/SUBMISSION_GUIDE.md

Store Submission Guide

Complete step-by-step instructions for submitting Context Bridge to Chrome Web Store and Firefox Add-ons.

---

Prerequisites

Before you start, make sure you have:

• ✅ Developer account (Chrome and/or Firefox)
• ✅ Extension packages (build/context-bridge-chrome.zip, build/context-bridge-firefox.zip)
• ✅ Icon assets (PNG icons in 16, 32, 48, 128px - generate if needed)
• ✅ Screenshots (5-8 images, 1280x800 or 1920x1080)
• ✅ Privacy policy URL (host PRIVACY_POLICY.md on GitHub Pages or your website)
• ✅ Payment method (Chrome: $5 one-time fee, Firefox: free)

---

Create Developer Accounts

Chrome Web Store

1. Go to: Chrome Web Store Developer Dashboard
2. Sign in with your Google account
3. Accept the Developer Agreement
4. Pay the one-time $5 registration fee
5. Done! You now have a Chrome Web Store developer account

Time: 5 minutes
Cost: $5 USD (one-time, non-refundable)

Firefox Add-ons (AMO)

1. Go to: Firefox Add-ons Developer Hub
2. Sign in or create a Firefox account
3. Accept the Developer Agreement
4. Done! You now have a Firefox Add-ons developer account

Time: 2 minutes
Cost: Free

---

Icon Generation

If you haven't generated PNG icons yet, do this first:

Option 1: ImageMagick (Command Line)

cd /Users/alexa/context-bridge/extension/icons

# Install ImageMagick (if not already installed)
brew install imagemagick

# Generate all sizes
for size in 16 32 48 128; do
  convert icon.svg -resize ${size}x${size} icon${size}.png
done

# Verify
ls -lh icon*.png

Option 2: Online Tool (No Installation)

1. Go to CloudConvert
2. Upload extension/icons/icon.svg
3. Set width/height to 128px
4. Download PNG
5. Repeat for 16px, 32px, 48px

Option 3: Figma/Sketch (Designers)

1. Open extension/icons/icon.svg in Figma/Sketch
2. Export as PNG at 16px, 32px, 48px, 128px
3. Save to extension/icons/

Required sizes: 16, 32, 48, 128 (all square)

---

Screenshot Preparation

What to Capture

5-8 screenshots showing:

1. Extension popup (configured with Gist URL)
2. ChatGPT with button ("Insert Context" button visible)
3. Claude with button ("Insert Context" button visible)
4. Context being inserted (mid-action shot)
5. Context inserted (full context in chat)
6. All 4 platforms (ChatGPT, Claude, Copilot, Gemini logos)
7. Before/After (copy-paste vs. one-click comparison)
8. Privacy diagram (optional: "Your Browser → GitHub → AI")

Screenshot Specs

Chrome Web Store:

• Size: 1280x800 or 640x400 (recommended)
• Format: PNG or JPG
• Max file size: 5 MB each
• Min: 1 screenshot, Max: 5 screenshots

Firefox Add-ons:

• Size: Any, but 1920x1080 or 1280x800 recommended
• Format: PNG or JPG
• Max file size: 10 MB each
• Max: 10 screenshots

Tools

• macOS: Cmd+Shift+4 (select area), Cmd+Shift+5 (screen recording)
• Windows: Win+Shift+S (Snip & Sketch)
• Linux: Flameshot, GNOME Screenshot
• Browser: CloudApp, Loom, Awesome Screenshot

Annotations (Optional)

Add arrows, highlights, text:

• Figma (free)
• Canva (free)
• Skitch (macOS, free)
• Paint.net (Windows, free)

---

Chrome Web Store Submission

Step 1: Upload Package

1. Go to Chrome Web Store Developer Dashboard
2. Click "New Item"
3. Click "Choose file"
4. Select build/context-bridge-chrome.zip
5. Click "Upload"

Wait: 1-2 minutes for upload and initial validation

Step 2: Store Listing

Fill in these fields (use CHROME_WEB_STORE_LISTING.md as reference):

Product Details

Extension name:

Context Bridge

Summary (132 chars max):

One-click AI context. Share context with ChatGPT, Claude, Copilot, and Gemini from your GitHub Gist.

Description (detailed, 16,000 chars max):

• Copy from CHROME_WEB_STORE_LISTING.md
• Includes: What is it, features, how it works, use cases, why it's better

Category:

Productivity

Language:

English (United States)

Graphic Assets

Icon (128x128):

• Upload extension/icons/icon128.png

Small tile (440x280, optional):

• Create a promotional tile with logo + tagline
• Or skip (Chrome will use icon)

Screenshots (1280x800):

• Upload 1-5 screenshots (prepared above)
• Add captions for each (optional but recommended)

Promotional images (optional):

• Small tile: 440x280
• Large tile: 920x680
• Marquee: 1400x560

Promotional video (optional):

• YouTube URL
• 30-90 seconds showing product in action

Privacy Practices

Privacy policy URL:

https://github.com/blackroad-os/context-bridge/blob/main/PRIVACY_POLICY.md

Or:

https://blackroad.io/privacy

Single purpose description:

Context Bridge allows users to insert pre-configured context from their GitHub Gist into AI chat interfaces with a single click, eliminating repetitive copy-pasting.

Permission justifications:

• storage: "To save the user's GitHub Gist URL locally for quick access."
• activeTab: "To insert context into the current AI chat page when the user clicks the button."

Data usage:

Context Bridge collects no user data. All context is stored in the user's GitHub Gist and fetched directly by the browser. No backend, no tracking, no data collection.

Distribution

Visibility:

• ✅ Public (visible to all users)
• Or Unlisted (only accessible via direct link - useful for beta testing)

Regions:

• ✅ All regions (unless you want to restrict)

Pricing:

• ✅ Free

Step 3: Review Settings

Test accounts (optional):

• If your extension requires login, provide test credentials
• Context Bridge doesn't need this (works with any GitHub Gist)

Notes for reviewers:

To test Context Bridge:
1. Create a GitHub Gist at https://gist.github.com (free account)
2. Add any text content (e.g., "This is my test context")
3. Copy the Gist URL
4. Click the Context Bridge icon in Chrome
5. Paste the Gist URL and click "Save"
6. Go to https://chat.openai.com (or https://claude.ai)
7. Look for the "Insert Context" button (top right of chat input)
8. Click the button - context appears in the chat

Test Gist URL: [paste your test Gist URL here]

Extension is privacy-first: no backend, no data collection, no tracking. All context goes directly from GitHub → Browser → AI platform.

Step 4: Submit for Review

1. Review all fields (double-check URLs, descriptions)
2. Click "Submit for review"
3. Wait: 1-7 days (usually 2-3 days)

Email notification: You'll receive an email when review is complete (approved or rejected)

---

Firefox Add-ons Submission

Step 1: Upload Package

1. Go to Firefox Add-ons Developer Hub
2. Click "Submit a New Add-on"
3. Click "Upload Add-on"
4. Select build/context-bridge-firefox.zip
5. Click "Continue"

Wait: 1-2 minutes for upload and validation

Step 2: Add-on Details

Basic Information

Name:

Context Bridge

Add-on URL (slug):

context-bridge

(Results in: https://addons.mozilla.org/firefox/addon/context-bridge)

Summary (250 chars max):

One-click AI context insertion. Share context with ChatGPT, Claude, Copilot, and Gemini from your GitHub Gist. No copy-paste, no context limits, no vendor lock-in. Privacy-first, open source.

Description (full, no limit):

• Copy from FIREFOX_ADDONS_LISTING.md
• More detailed than Chrome (Firefox users appreciate technical depth)

Homepage:

https://github.com/blackroad-os/context-bridge

Support email:

support@blackroad.io

Support website (optional):

https://github.com/blackroad-os/context-bridge/discussions

License:

MIT License

Privacy policy:

https://github.com/blackroad-os/context-bridge/blob/main/PRIVACY_POLICY.md

Categories and Tags

Categories (select 2):

• ✅ Productivity
• ✅ Developer Tools

Tags (max 20, space-separated):

ai chatgpt claude copilot gemini context gist github productivity developer privacy open-source

Screenshots and Media

Screenshots (max 10):

• Upload 5-8 screenshots (prepared above)
• Firefox recommends 1920x1080 (but any size works)

Icon (64x64 or 128x128):

• Upload extension-firefox/icons/icon128.png

Version Notes

Version number:

1.0.0

Release notes:

Initial release!

Features:
- One-click context insertion into ChatGPT, Claude, GitHub Copilot, and Google Gemini
- GitHub Gist integration (use your existing Gists)
- Smart caching (30x faster after first use)
- Privacy-first (zero backend, no tracking)
- Open source (MIT License)

Supported platforms:
- ChatGPT (chat.openai.com, chatgpt.com)
- Claude (claude.ai)
- GitHub Copilot (github.com)
- Google Gemini (gemini.google.com)

Learn more: https://github.com/blackroad-os/context-bridge

Step 3: Technical Details

Does this add-on require any additional information or instructions?

• ✅ No (Context Bridge is self-explanatory)

Source code submission (required for Firefox):

• Click "Upload source code"
• Upload context-bridge-firefox-source.zip (create this - see below)
• Or link to GitHub: https://github.com/blackroad-os/context-bridge

Build instructions (if source code differs from package):

No build process. Extension uses vanilla JavaScript with no dependencies.
Source code is identical to the uploaded package (no minification, no bundling).

To verify:
1. Unzip context-bridge-firefox.zip
2. Compare with GitHub source: https://github.com/blackroad-os/context-bridge

Step 4: Submit for Review

1. Review all fields
2. Click "Submit Version"
3. Wait: 1-14 days (usually 3-5 days)

Note: Firefox reviews are more thorough than Chrome (manual code review).

---

Source Code Package (Firefox Only)

Firefox requires source code submission if your package differs from source.

Create Source ZIP

cd /Users/alexa/context-bridge

# Create source package
zip -r build/context-bridge-firefox-source.zip \
  extension-firefox/ \
  README.md \
  PRIVACY_POLICY.md \
  LICENSE \
  -x "*.DS_Store" "*.git*"

# Verify
unzip -l build/context-bridge-firefox-source.zip

Or just link to GitHub (easier):

https://github.com/blackroad-os/context-bridge

Firefox reviewers prefer GitHub links (they can see commit history).

---

Review Process

Chrome Web Store

Timeline: 1-7 days (average: 2-3 days)

Review criteria:

1. ✅ Follows Chrome Web Store policies
2. ✅ Permissions match functionality
3. ✅ No malicious code
4. ✅ No misleading claims
5. ✅ Privacy policy provided

Common rejection reasons:

• Overly broad permissions (Context Bridge only requests storage + activeTab ✅)
• Missing privacy policy (we have one ✅)
• Misleading description (ours is accurate ✅)
• Trademark issues (no trademarks used ✅)

If approved: Extension goes live immediately

If rejected: Email with reason + 30 days to fix and resubmit

Firefox Add-ons

Timeline: 1-14 days (average: 3-5 days)

Review types:

• Automated review (minutes): Checks for common issues
• Manual review (days): Human reviewer examines code

Review criteria:

1. ✅ Follows AMO policies
2. ✅ Source code matches package
3. ✅ No obfuscated code
4. ✅ Permissions justified
5. ✅ Privacy policy provided

Common rejection reasons:

• Obfuscated/minified code (Context Bridge uses vanilla JS ✅)
• Missing source code (we provide it ✅)
• Undeclared permissions (all declared ✅)
• Remote code execution (we don't do this ✅)

If approved: Extension goes live on next review cycle (usually within hours)

If rejected: Email with detailed feedback + option to respond/fix

---

After Approval

Chrome Web Store

1. Extension goes live (immediately)
2. Store URL: https://chrome.google.com/webstore/detail/YOUR_EXTENSION_ID
3. Update marketing materials with store URL
4. Monitor: Developer Dashboard

Metrics available:

• Installs (total, weekly, daily)
• Uninstalls
• User ratings and reviews
• Impressions (store page views)

Firefox Add-ons

1. Extension goes live (within hours of approval)
2. Store URL: https://addons.mozilla.org/firefox/addon/context-bridge
3. Update marketing materials with store URL
4. Monitor: Developer Hub Statistics

Metrics available:

• Downloads (total, weekly, daily)
• Active users (daily, weekly)
• User ratings and reviews
• Update adoption rate

---

Updating Your Extension

Chrome Web Store

1. Update version in extension/manifest.json (e.g., 1.0.0 → 1.1.0)
2. Make your changes
3. Re-package: bash package-for-submission.sh
4. Go to Developer Dashboard
5. Click on "Context Bridge"
6. Click "Package" → "Upload new package"
7. Upload new ZIP
8. Update release notes
9. Click "Submit for review"

Review time: Usually faster (1-2 days) for updates

Auto-updates: Users get the update automatically within 5 hours

Firefox Add-ons

1. Update version in extension-firefox/manifest.json
2. Make your changes
3. Re-package: bash package-for-submission.sh
4. Go to Developer Hub
5. Click on "Context Bridge"
6. Click "Upload New Version"
7. Upload new ZIP
8. Update release notes
9. Submit source code (if changed)
10. Click "Submit Version"

Review time: 1-7 days (depends on changes)

Auto-updates: Users get the update automatically within 24 hours

---

Troubleshooting

"Package upload failed"

Chrome:

• Check manifest.json is valid JSON
• Ensure all files referenced in manifest exist
• Max package size: 20 MB (Context Bridge is 24 KB ✅)

Firefox:

• Check manifest.json is valid JSON
• Ensure manifest_version is 2 (not 3)
• Max package size: 200 MB (Context Bridge is 23 KB ✅)

"Invalid manifest"

Common issues:

• Missing required fields (name, version, manifest_version)
• Invalid permissions syntax
• Incorrect file paths in content_scripts

Fix:

cd /Users/alexa/context-bridge
# Validate Chrome manifest
node -e "console.log(JSON.parse(require('fs').readFileSync('extension/manifest.json')))"

# Validate Firefox manifest
node -e "console.log(JSON.parse(require('fs').readFileSync('extension-firefox/manifest.json')))"

"Privacy policy required"

Chrome: Privacy policy URL is required if extension handles user data

Fix: Add privacy policy URL in "Privacy Practices" section

Context Bridge: We have one! https://github.com/blackroad-os/context-bridge/blob/main/PRIVACY_POLICY.md

"Permission justification needed"

Chrome: Must explain why each permission is needed

Fix: Add clear justifications:

• storage: "To save the user's GitHub Gist URL locally."
• activeTab: "To insert context into the current AI chat page."

"Misleading description"

Issue: Description promises features that don't exist

Fix: Be accurate. Context Bridge description is tested and accurate.

"Source code doesn't match package" (Firefox)

Issue: Uploaded package differs from source code

Fix: Context Bridge has no build process (vanilla JS), so they match. Explain this in build instructions.

---

Best Practices

Before Submitting

• ✅ Test extension thoroughly on all 4 platforms
• ✅ Clear, accurate description (no hype)
• ✅ All required fields filled
• ✅ Screenshots show actual product (no mockups)
• ✅ Privacy policy URL works
• ✅ Support email is monitored

During Review

• ✅ Respond to reviewer questions within 24 hours
• ✅ Be respectful and professional
• ✅ Provide test credentials if needed
• ✅ Don't submit repeatedly (wait for review to complete)

After Approval

• ✅ Monitor user reviews daily
• ✅ Respond to negative reviews (politely, helpfully)
• ✅ Fix critical bugs within 48 hours
• ✅ Update documentation as needed
• ✅ Thank early reviewers

---

Rejection Appeal

If Chrome Rejects

1. Read the rejection email carefully
2. Fix the issues mentioned
3. Re-submit (free, unlimited attempts)
4. If you disagree, use the appeal form (rare)

If Firefox Rejects

1. Read the rejection email (very detailed)
2. Respond via the review system (ask questions!)
3. Fix issues and re-submit
4. Firefox reviewers are helpful - work with them

---

Launch Checklist

After both extensions are approved:

• Update README.md with store URLs
• Update QUICKSTART.md with store URLs
• Update FAQ.md with store URLs
• Update all marketing materials with store URLs
• Add Chrome badge to README: [![Chrome Web Store](https://img.shields.io/chrome-web-store/v/YOUR_ID)](URL)
• Add Firefox badge to README: [![Mozilla Add-on](https://img.shields.io/amo/v/context-bridge)](URL)
• Tweet the store URLs
• Post on LinkedIn
• Submit to Product Hunt
• Post on Reddit (r/SideProject first)
• Celebrate! 🎉

---

Support During Review

Need help? Contact:

• Chrome: Chrome Web Store Support
• Firefox: AMO Developer Support
• Community: GitHub Discussions

---

Ready to submit? Follow this guide step-by-step, and you'll be live in a week! 🚀