From e02a489717663635a63cc0f800ca5af6ad928446 Mon Sep 17 00:00:00 2001 From: Patrick Schiller
Date: Sat, 15 Aug 2026 10:40:55 +0200 Subject: [PATCH] Add public launch kit Signed-off-by: Patrick Schiller
---
marketing/COMMUNITY_POSTS.md | 95 ++++++++++++++++++++++++
marketing/DEMO_SCRIPT.md | 90 +++++++++++++++++++++++
marketing/GITHUB.md | 134 ++++++++++++++++++++++++++++++++++
marketing/LAUNCH_CHECKLIST.md | 120 ++++++++++++++++++++++++++++++
marketing/PRODUCT_HUNT.md | 76 +++++++++++++++++++
marketing/README.md | 77 +++++++++++++++++++
marketing/SHOW_HN.md | 50 +++++++++++++
7 files changed, 642 insertions(+)
create mode 100644 marketing/COMMUNITY_POSTS.md
create mode 100644 marketing/DEMO_SCRIPT.md
create mode 100644 marketing/GITHUB.md
create mode 100644 marketing/LAUNCH_CHECKLIST.md
create mode 100644 marketing/PRODUCT_HUNT.md
create mode 100644 marketing/README.md
create mode 100644 marketing/SHOW_HN.md
diff --git a/marketing/COMMUNITY_POSTS.md b/marketing/COMMUNITY_POSTS.md
new file mode 100644
index 0000000..25b042d
--- /dev/null
+++ b/marketing/COMMUNITY_POSTS.md
@@ -0,0 +1,95 @@
+# Community post drafts
+
+These drafts deliberately use different frames. Before posting, read the current
+community rules, search for recent project posts, disclose that you built
+SourceBraid, and participate in the discussion. Never post all three on the same
+day or reuse an identical title and body.
+
+## r/selfhosted
+
+Suggested title:
+
+> I built a GitHub-backed web-to-Markdown archive with no central content server
+
+Draft:
+
+> I have been building SourceBraid, an open-source tool that saves web pages,
+> papers, wikis, Gists, and PDFs as Markdown in a private GitHub repository the
+> user controls.
+>
+> I want to be precise about the "self-hosted" angle: SourceBraid is not a server
+> you deploy, and it depends on GitHub as the durable remote store. There is no
+> central SourceBraid content service. The Markdown files, assets, metadata
+> shards, and Git history live in the selected repository; the SQLite full-text
+> index is a disposable local cache.
+>
+> Capture is available through the public clients listed here: {{PUBLIC_URL}}.
+> PDF conversion can run in the user's repository through GitHub Actions and
+> Docling. The project is MIT-licensed: {{REPOSITORY_URL}}.
+>
+> I would value a self-hosting community critique of this architecture. Does a
+> user-controlled GitHub repository provide a useful ownership boundary for this
+> workflow, or is a non-Git remote backend important before you would consider
+> using it?
+
+## r/PKMS
+
+Suggested title:
+
+> My web-clipping workflow now ends in portable Markdown instead of another inbox
+
+Draft:
+
+> I built SourceBraid around a simple personal-knowledge-management preference:
+> after I save a source, I want a readable file with provenance, not only a URL
+> and not a record trapped inside a service.
+>
+> SourceBraid captures articles, research papers, wikis, Gists, and PDFs into a
+> private GitHub repository. It adds YAML frontmatter, keeps relevant images as
+> relative assets, records notes and tags, and uses Git history for inspectable
+> changes. A ChatGPT/Codex plugin can search and fetch the resulting archive.
+>
+> Demo: {{DEMO_URL}}
+> Source: {{REPOSITORY_URL}}
+>
+> I am interested in how people would fit this into an existing PKM system. Would
+> you keep the captured archive separate from your own notes, link the two, or
+> import selected sources into the same vault? I am trying to preserve the
+> distinction between source material and personal synthesis.
+
+## r/opensource
+
+Suggested title:
+
+> SourceBraid: an MIT-licensed web-to-Markdown archive built on Git history
+
+Draft:
+
+> I am releasing SourceBraid, an open-source capture and retrieval workflow for
+> people who want their web research as portable Markdown.
+>
+> The capture clients save pages, papers, wikis, Gists, and PDFs into a private
+> GitHub repository selected by the user. The project has no central content
+> server. Markdown and Git history are authoritative, while the local SQLite
+> search index can be deleted and rebuilt. The code is MIT-licensed, with a
+> Manifest V3 Chrome extension, a native iOS app/Share Extension, and a
+> dependency-free Python plugin for ChatGPT and Codex. Remove any client from
+> this sentence that is not public for `{{VERSION}}`.
+>
+> Repository: {{REPOSITORY_URL}}
+> Release: {{RELEASE_URL}}
+>
+> The areas where contributions would be most useful are reproducible extraction
+> fixtures, accessibility feedback, additional trustworthy source adapters, and
+> review of the permission and privacy explanations. Please do not include real
+> private archives or copyrighted captured material in issues or test fixtures.
+
+## Moderation and follow-up
+
+- If a moderator removes a post, do not repost it without permission.
+- Answer architectural criticism with concrete tradeoffs and documentation.
+- Move reproducible bugs to GitHub Issues only after acknowledging them in the
+ original thread.
+- Do not treat disagreement about GitHub as hostility; it is a central product
+ tradeoff and useful launch feedback.
+- Record repeated questions for the week-one launch recap.
diff --git a/marketing/DEMO_SCRIPT.md b/marketing/DEMO_SCRIPT.md
new file mode 100644
index 0000000..151b42c
--- /dev/null
+++ b/marketing/DEMO_SCRIPT.md
@@ -0,0 +1,90 @@
+# 60-second demo script
+
+## Demo contract
+
+Show a complete, truthful path from source to owned Markdown to retrieval. Use a
+new private synthetic repository and either SourceBraid's own public material or
+a source with clearly verified redistribution permission. Record no personal
+tabs, browser history, notifications, tokens, existing private repository names,
+or existing private clips.
+
+Rehearse once from a clean public installation. Keep the pointer still except
+when it identifies the next action, and make every label readable at 1080p.
+
+## Storyboard
+
+### 0-6 seconds: the outcome
+
+Visual: A useful public source in Chrome. Cut briefly to its clean Markdown file
+in the synthetic private GitHub repository.
+
+Voiceover:
+
+> This source will still be useful to me if the page changes or the app goes
+> away. SourceBraid turns it into Markdown in a GitHub repository I control.
+
+On-screen text:
+
+> Web to Markdown. Your repository.
+
+### 6-18 seconds: capture
+
+Visual: Open SourceBraid, add the synthetic tag `demo` and note `Review the
+provenance section`, then select **Save to GitHub**.
+
+Voiceover:
+
+> I can add my own tags and notes before saving. SourceBraid chooses the best
+> available extraction path and preserves where the source came from.
+
+Do not expose the GitHub token or expand settings during the recording.
+
+### 18-34 seconds: inspect the archive
+
+Visual: Open the resulting Markdown file. Point out the YAML frontmatter,
+readable body, relative image reference when present, and normal Git commit.
+
+Voiceover:
+
+> The result is an ordinary Markdown file with provenance, local assets when
+> needed, and normal Git history. The archive remains understandable without a
+> proprietary SourceBraid format.
+
+### 34-50 seconds: retrieve
+
+Visual: In ChatGPT or Codex, use the public plugin path and ask:
+
+> Search my SourceBraid archive for the demo source and show its provenance.
+
+Show the matching result and source path. Do not show a deletion operation in
+the primary demo; it distracts from the capture-to-retrieval story.
+
+Voiceover:
+
+> The SourceBraid plugin searches the archive and returns the saved source with
+> its repository path and provenance.
+
+### 50-60 seconds: trust and action
+
+Visual: Three quick frames: Chrome capture, Markdown repository, search result.
+End on the product name and one public install URL.
+
+Voiceover:
+
+> There is no central SourceBraid content server. Your archive lives in the
+> GitHub repository you choose. SourceBraid is open source and available at
+> sourcebraid.com.
+
+On-screen text:
+
+> SourceBraid - Weave the web into Markdown.
+
+## Export checklist
+
+- [ ] The exact clients shown are publicly available.
+- [ ] The source and all visible content are redistributable.
+- [ ] Captions match the spoken script.
+- [ ] No token, account identifier, private content, or personal browser chrome
+ appears in any frame.
+- [ ] The final CTA resolves in a signed-out browser.
+- [ ] A silent viewer can understand the three-step story.
diff --git a/marketing/GITHUB.md b/marketing/GITHUB.md
new file mode 100644
index 0000000..33407cb
--- /dev/null
+++ b/marketing/GITHUB.md
@@ -0,0 +1,134 @@
+# GitHub launch metadata
+
+Repository: `patrickschiller/sourcebraid`
+
+## About section
+
+Description:
+
+> Weave the web into durable Markdown in your own GitHub repository.
+
+Website:
+
+> https://sourcebraid.com
+
+The social preview should use
+`assets/branding/sourcebraid-social-card.png` and must be checked at desktop and
+mobile sizes before launch.
+
+## Topics
+
+Use this initial topic set:
+
+```text
+web-clipper
+markdown
+read-it-later
+web-archiving
+personal-knowledge-management
+knowledge-base
+browser-extension
+chrome-extension
+ios
+github
+privacy
+mcp-server
+codex-plugin
+full-text-search
+pdf-to-markdown
+```
+
+Apply the set after authenticating `gh` as a repository administrator:
+
+```bash
+gh repo edit patrickschiller/sourcebraid \
+ --add-topic web-clipper \
+ --add-topic markdown \
+ --add-topic read-it-later \
+ --add-topic web-archiving \
+ --add-topic personal-knowledge-management \
+ --add-topic knowledge-base \
+ --add-topic browser-extension \
+ --add-topic chrome-extension \
+ --add-topic ios \
+ --add-topic github \
+ --add-topic privacy \
+ --add-topic mcp-server \
+ --add-topic codex-plugin \
+ --add-topic full-text-search \
+ --add-topic pdf-to-markdown
+```
+
+The order above starts with user intent and moves toward implementation details.
+Do not add `self-hosted`, `local-first`, or `offline-first` unless the product
+contract changes enough to make those expectations accurate.
+
+Review topics for every coordinated public release and once per quarter. Remove
+a topic when the corresponding user-facing behavior is no longer supported.
+Add a topic only when it describes a shipped, documented capability. Twice a
+year, compare the vocabulary used by adjacent web-clipping and archiving
+projects; do not copy irrelevant implementation topics merely because they are
+popular.
+
+## Repository features
+
+Before the public launch:
+
+- apply and verify the documented topic set on the live repository;
+- enable GitHub Discussions;
+- retain Issues for actionable bugs and feature work;
+- create Discussion categories `Announcements`, `Ideas`, `Q&A`, and
+ `Show and tell`;
+- pin a welcome discussion explaining when to use Discussions versus Issues;
+- publish the coordinated GitHub release and attach the allowlisted artifacts;
+- verify the README's primary install links point to published destinations;
+- verify the English and German READMEs describe the same available clients.
+
+Suggested welcome discussion title:
+
+> Welcome to SourceBraid: questions, workflows, and ideas
+
+Suggested welcome text:
+
+> SourceBraid is an open-source web-to-Markdown archive built around files and
+> Git history that the user controls. Use Q&A for setup questions, Ideas for
+> early product discussion, and Show and tell for workflows you have built.
+> Please use Issues for reproducible bugs and scoped implementation requests.
+> Do not post access tokens, private repository names, or captured content that
+> you do not have permission to share.
+
+## Release description template
+
+```markdown
+# SourceBraid {{VERSION}}
+
+SourceBraid saves web pages, papers, wikis, Gists, and PDFs as portable Markdown
+in a private GitHub repository controlled by the user. This coordinated release
+includes the supported capture clients and ChatGPT/Codex archive tools listed
+below.
+
+## Install
+
+- Chrome: {{CHROME_STORE_URL}}
+- iPhone and iPad: {{APP_STORE_URL}}
+- ChatGPT and Codex plugin: {{PLUGIN_URL}}
+
+Remove any installation line whose destination is not public for this release.
+
+## Highlights
+
+- [Three verified, user-visible highlights for this exact release]
+
+## Privacy and permissions
+
+SourceBraid has no central content server. Capture clients write to the GitHub
+repository selected by the user. Review the permissions and data flow in the
+[privacy notice](https://github.com/patrickschiller/sourcebraid/blob/main/PRIVACY.md).
+
+## Checks
+
+- `node --test tests/capture-utils.test.js`
+- `python3 -m unittest discover -s tests -p "test_*.py"`
+- unsigned iOS simulator build
+- public release safety and artifact inspection
+```
diff --git a/marketing/LAUNCH_CHECKLIST.md b/marketing/LAUNCH_CHECKLIST.md
new file mode 100644
index 0000000..1f691ef
--- /dev/null
+++ b/marketing/LAUNCH_CHECKLIST.md
@@ -0,0 +1,120 @@
+# Coordinated launch checklist
+
+This checklist supplements `RELEASING.md`. The release procedure remains the
+authority for packaging, versioning, private-content exclusions, and required
+checks.
+
+## Launch gate
+
+Do not begin the public launch wave until all checked channels are directly
+usable. A landing page, waitlist, TestFlight-only build, or local plugin install
+does not count as a public destination.
+
+- [ ] Define the exact coordinated release version: `{{VERSION}}`.
+- [ ] Align Chrome, plugin, iOS app, and Share Extension versions.
+- [ ] Confirm the public `main` commit contains no private website or archive
+ content and no unrelated authoring changes.
+- [ ] Run every required check in `RELEASING.md`.
+- [ ] Build artifacts through the allowlisted package builders.
+- [ ] Inspect archive contents and record their SHA-256 digests.
+- [ ] Publish a GitHub release at `{{RELEASE_URL}}`.
+- [ ] Publish and verify every store or plugin destination that will be named.
+- [ ] For the OpenAI submission, confirm the publishing organization grants the
+ submitter `Apps Management: Write` and uses a verified developer or business
+ identity.
+- [ ] Complete the plugin listing information, skills or MCP details, starter
+ prompts, test cases, country availability, and policy attestations required by
+ the [official OpenAI submission guide](https://developers.openai.com/plugins/deploy/submission).
+- [ ] Complete one clean installation from each public destination.
+- [ ] Complete first-run GitHub setup using a new private synthetic repository.
+- [ ] Save one HTML source and one PDF, then verify Markdown, frontmatter,
+ assets, index metadata, and Git history.
+- [ ] Search the synthetic archive from the published plugin path.
+- [ ] Verify privacy, terms, support, and repository links from every listing.
+- [ ] Verify English and German user-facing documentation remain aligned.
+
+## Launch assets
+
+- [ ] Record the workflow in `DEMO_SCRIPT.md` using synthetic or clearly
+ redistributable content.
+- [ ] Export a captioned 16:9 video and a readable silent GIF or short MP4.
+- [ ] Prepare Chrome Web Store screenshots showing capture, repository output,
+ and search rather than decorative branding alone.
+- [ ] Prepare localized App Store screenshots for English and German.
+- [ ] Verify all screenshots use synthetic repository names, notes, tags, and
+ content, and contain no tokens, account identifiers, or private user data.
+- [ ] Replace all launch variables and run:
+
+ ```bash
+ rg -n '\{\{[A-Z0-9_]+\}\}' marketing
+ ```
+
+- [ ] Have another person follow the public installation instructions without
+ private maintainer context.
+
+## Soft launch
+
+- [ ] Recruit 15-25 testers from the initial audience, without public upvote or
+ review requests.
+- [ ] Ask each tester to complete installation, first capture, and first search.
+- [ ] Record friction by step, not only general impressions.
+- [ ] Fix release-blocking permission, onboarding, and data-loss risks.
+- [ ] Collect permission before quoting any feedback publicly.
+- [ ] Enable GitHub Discussions and publish the welcome discussion.
+
+## Public launch order
+
+Stagger posts so the maintainer can answer every substantive question.
+
+1. Publish the GitHub release and canonical website update.
+2. Verify store and plugin pages from a signed-out browser.
+3. Publish the demo and the technical launch article.
+4. Post Show HN while available for live discussion.
+5. Post to one relevant Reddit community with its tailored draft.
+6. Launch on Product Hunt on a separate day.
+7. Post to the remaining communities only when there is a genuine audience fit.
+8. Submit accurate listings to AlternativeTo and suitable open-source
+ directories after the canonical release URLs are stable.
+
+Do not cross-post identical text, ask anyone to coordinate votes, or post to
+communities whose self-promotion rules prohibit the submission.
+
+## Launch-day response desk
+
+- [ ] Reserve two focused response windows in both European and US waking hours.
+- [ ] Keep concise answers ready for GitHub token scope, `