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, ``, PDF + conversion, private repositories, deletion safety, and the lack of a central + SourceBraid content server. +- [ ] Convert reproducible defects into Issues; keep broad questions in + Discussions. +- [ ] Publish corrections visibly if a listing or post overstates a capability. +- [ ] Never request access to a user's private archive for ordinary support. + +## Measurement + +Use aggregate, privacy-respecting signals. The primary launch outcome is a +successful first capture, not GitHub stars. + +| Funnel step | Minimum signal | +| --- | --- | +| Discovery | Website visits, repository visitors, store impressions | +| Intent | Install-link clicks or store product-page views | +| Install | Store installs or plugin installs | +| Activation | First successful capture into the selected repository | +| Value | First successful archive search | +| Retention | A second capture within seven days | + +Where product instrumentation is not available, use store analytics, GitHub +traffic, opt-in tester reports, and privacy-preserving aggregate website data. +Do not collect captured URLs, titles, notes, tags, repository names, or search +queries for launch measurement. + +## Week-one follow-up + +- [ ] Publish a transparent recap: what worked, what confused people, and what + will change next. +- [ ] Triage support and defects before starting another promotion wave. +- [ ] Update installation copy where repeated questions reveal ambiguity. +- [ ] Compare activation by destination, not vanity traffic alone. +- [ ] Thank contributors and testers only with their permission. +- [ ] Choose the next content artifact from observed user questions. diff --git a/marketing/PRODUCT_HUNT.md b/marketing/PRODUCT_HUNT.md new file mode 100644 index 0000000..5ba31c7 --- /dev/null +++ b/marketing/PRODUCT_HUNT.md @@ -0,0 +1,76 @@ +# Product Hunt launch draft + +Publish only when the product is immediately installable through at least one +public destination. Remove unavailable platform links rather than promising +them in the listing. + +## Main listing + +Name: + +> SourceBraid + +Tagline: + +> Weave the web into Markdown you own + +Description: + +> Save web pages, papers, wikis, Gists, and PDFs as durable Markdown in a private +> GitHub repository you control, then search the archive from ChatGPT and Codex. + +Primary URL: + +> {{PUBLIC_URL}} + +Additional links: + +- Repository: {{REPOSITORY_URL}} +- Chrome: {{CHROME_STORE_URL}} +- iPhone and iPad: {{APP_STORE_URL}} +- ChatGPT and Codex: {{PLUGIN_URL}} + +Choose no more than three current Product Hunt categories that reflect the +shipped product. Prefer the closest equivalents of productivity, knowledge +management, and open source; verify the live taxonomy during submission. + +## Gallery order + +1. 45-60 second capture-to-search demo; +2. Chrome capture with tags and notes; +3. readable Markdown and provenance in the private synthetic repository; +4. ChatGPT or Codex search result; +5. simple data-flow graphic explaining that there is no central content server. + +## Maker comment + +> Hi Product Hunt - I built SourceBraid because I wanted saved research to end +> up as files I could inspect, search, move, and keep, rather than as records +> inside another service. +> +> SourceBraid captures web pages, papers, wikis, Gists, and PDFs as Markdown in +> a private GitHub repository selected by the user. It preserves provenance, +> stores relevant assets next to the document, and uses normal Git commits. A +> ChatGPT/Codex plugin adds full-text search, fetching, and guarded archive +> management without making a SourceBraid database the source of truth. +> +> The privacy boundary shaped the architecture: SourceBraid has no central +> content server. The capture clients communicate with source websites and the +> GitHub repository the user configured. The Markdown files and Git history are +> authoritative; the local SQLite search index is disposable and rebuildable. +> +> The project is MIT-licensed. I would especially value feedback on first-run +> GitHub setup, the permission explanation, and which research workflows deserve +> a dedicated extraction adapter next. +> +> Demo: {{DEMO_URL}} +> Source: {{REPOSITORY_URL}} + +## Launch-day answers to prepare + +- Why GitHub instead of local storage or a hosted database? +- Which GitHub token permissions are required, and why? +- What happens if GitHub or SourceBraid is unavailable? +- How are PDFs converted and which limits apply? +- How does this differ from a bookmark manager or a faithful HTML snapshot? +- Can an existing Markdown archive be used without lock-in? diff --git a/marketing/README.md b/marketing/README.md new file mode 100644 index 0000000..50a35d7 --- /dev/null +++ b/marketing/README.md @@ -0,0 +1,77 @@ +# SourceBraid launch kit + +This directory contains the public launch material for SourceBraid. Keep claims +aligned with the release that people can actually install. The launch material +must never include private archive content, credentials, analytics identifiers, +or screenshots of a real user's repository. + +## Core message + +**SourceBraid turns web pages, papers, wikis, Gists, and PDFs into durable +Markdown in a private GitHub repository controlled by the user. The archive can +then be searched and managed from ChatGPT and Codex.** + +Short version: + +> Weave the web into Markdown you own. + +SourceBraid is not a hosted bookmark service, a collaboration network, or a +claim that captured third-party content becomes MIT-licensed. Avoid describing +it as `offline-first`, `local-first`, or fully `self-hosted`: GitHub is the +durable remote store and some workflows require GitHub Actions. + +## Audience + +Launch first to people who already value at least two of these: + +- Markdown and portable files; +- private, user-controlled archives; +- GitHub-based workflows; +- research papers, technical documentation, or long-lived web research; +- retrieval from ChatGPT or Codex. + +Do not lead with a generic bookmark-manager comparison. The narrower wedge is a +GitHub-native web-to-Markdown research archive. + +## Launch variables + +Replace every variable before publishing a draft. A missing channel is removed +from that draft rather than presented as "coming soon." + +| Variable | Value | +| --- | --- | +| `{{VERSION}}` | Coordinated public release version | +| `{{PUBLIC_URL}}` | `https://sourcebraid.com` | +| `{{REPOSITORY_URL}}` | `https://github.com/patrickschiller/sourcebraid` | +| `{{RELEASE_URL}}` | Public GitHub release | +| `{{CHROME_STORE_URL}}` | Published Chrome Web Store listing | +| `{{APP_STORE_URL}}` | Published App Store listing | +| `{{PLUGIN_URL}}` | Published ChatGPT/Codex plugin listing | +| `{{DEMO_URL}}` | Public demo video with synthetic or redistributable content | + +Find unresolved variables before publishing: + +```bash +rg -n '\{\{[A-Z0-9_]+\}\}' marketing +``` + +## Files + +- [`GITHUB.md`](GITHUB.md): repository metadata, topics, and community setup; +- [`LAUNCH_CHECKLIST.md`](LAUNCH_CHECKLIST.md): release gates and launch order; +- [`DEMO_SCRIPT.md`](DEMO_SCRIPT.md): 60-second product demo; +- [`PRODUCT_HUNT.md`](PRODUCT_HUNT.md): listing and maker comment; +- [`SHOW_HN.md`](SHOW_HN.md): technical launch post; +- [`COMMUNITY_POSTS.md`](COMMUNITY_POSTS.md): tailored Reddit drafts. + +## Voice and proof rules + +- Explain the user-controlled data flow before listing extraction adapters. +- Prefer one real workflow over a long feature inventory. +- Say exactly which clients and stores are available in the current release. +- Use "private GitHub repository" only when showing a private synthetic demo + repository with no private user content. +- Never imply that SourceBraid bypasses paywalls, access controls, or publisher + permissions. +- Never ask for coordinated upvotes, reviews, stars, or comments. +- Answer launch-day questions directly, including permission and token concerns. diff --git a/marketing/SHOW_HN.md b/marketing/SHOW_HN.md new file mode 100644 index 0000000..480bf24 --- /dev/null +++ b/marketing/SHOW_HN.md @@ -0,0 +1,50 @@ +# Show HN draft + +Submit the canonical website or repository URL. The destination must let an HN +reader inspect the source and install a working public release without joining a +waitlist or requesting access. + +## Title + +> Show HN: SourceBraid - Save web pages and papers as Markdown in your GitHub repo + +## Submission text + +> Hi HN, +> +> I built SourceBraid because I wanted the output of web clipping to be ordinary +> files that I control. It saves web pages, papers, wikis, GitHub Gists, and PDFs +> as Markdown in a private GitHub repository selected by the user. Relevant +> images are stored beside the document, provenance is kept in YAML frontmatter, +> and each change is a normal Git commit. +> +> The repository is the source of truth. SourceBraid has no central content +> server, and its local SQLite FTS5 index is only a rebuildable search cache. A +> ChatGPT/Codex plugin can search and fetch saved sources and uses a guarded +> preview-and-confirm flow before deletion. +> +> A detail I spent time on is choosing the strongest trustworthy representation +> before falling back to generic DOM extraction. For example, SourceBraid can use +> full-paper arXiv HTML, source Markdown from a GitHub Gist or authenticated Azure +> DevOps Wiki, and a GitHub Actions/Docling path for PDFs. The resulting archive +> still consists of Markdown, assets, metadata shards, and Git history. +> +> The Chrome extension is Manifest V3 with no build step or third-party runtime. +> The plugin is dependency-free Python and uses SQLite FTS5. There is also a +> native iOS Share Extension. Only retain this sentence if all three are public +> for `{{VERSION}}`. +> +> Demo: {{DEMO_URL}} +> Source and installation: {{REPOSITORY_URL}} +> +> I would appreciate feedback on the GitHub permission model, the capture format, +> and whether the boundary between faithful archiving and readable Markdown feels +> right. I will be here to answer technical questions. + +## Before submitting + +- [ ] Replace or remove the platform sentence so it names only public clients. +- [ ] Replace every launch variable. +- [ ] Install from the submitted destination in a signed-out browser. +- [ ] Confirm the maintainer is available to answer comments for several hours. +- [ ] Do not ask anyone to upvote or seed comments.