Skip to content

Prepare SourceBraid 1.1.0 plugin releases and onboarding plan #21

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
patrickschiller wants to merge 3 commits into from
Closed

Prepare SourceBraid 1.1.0 plugin releases and onboarding plan #21

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
467542a
Prepare SourceBraid 1.1.0 plugins and publishing plans
patrickschiller Oct 15, 2026
2bb4a13
Update iOS and iPadOS onboarding plan after 1.1.0
patrickschiller Oct 15, 2026
e587c15
Align planned onboarding destination with Recent naming
patrickschiller Oct 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,9 @@ xcuserdata/
*.xcuserstate
ios/build/

# Local handoff notes stay outside version control.
/HANDOFF.md

# Release archives are published separately.
dist/

Expand Down
62 changes: 41 additions & 21 deletions README.de.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,15 +20,17 @@ Git-Historie, die auch ohne SourceBraid nützlich bleiben.
## So funktioniert SourceBraid

SourceBraid verbindet Capture-Clients, ein privates GitHub-Repository als
dauerhaft maßgebliche Datenquelle und zwei Zugriffswege. Das lokale Codex-Plugin
unterstützt Suche und Archivverwaltung. Die gehostete ChatGPT-Integration mit
reinem Lesezugriff ist für Bereitstellung und Prüfung vorbereitet; sie ist noch
kein öffentlich verfügbarer Dienst. Chrome-Erweiterung und iOS-App schreiben
dauerhaft maßgebliche Datenquelle und drei Zugriffswege. Die iOS-App bietet
einen lokalen Reader, Offline-Suche und optionalen Chat auf dem Gerät. Das lokale
Codex-Plugin unterstützt Suche und Archivverwaltung. Die gehostete
ChatGPT-Integration mit reinem Lesezugriff ist für Bereitstellung und Prüfung
vorbereitet; sie ist noch kein öffentlich verfügbarer Dienst.
Chrome-Erweiterung und iOS-App schreiben
Captures direkt in das konfigurierte GitHub-Repository. Gehostete
ChatGPT-Anfragen laufen künftig über den SourceBraid-Worker bei Cloudflare,
ohne eine dauerhafte Inhaltsdatenbank anzulegen.

Der lokale SQLite-Index ist nur ein jederzeit neu aufbaubarer Such-Cache.
Lokale SQLite-Indizes sind nur jederzeit neu aufbaubare Such-Caches.
Maßgeblich bleiben die Markdown-Dateien und die Git-Historie.

```mermaid
Expand Down Expand Up @@ -56,6 +58,8 @@ flowchart TD
Q --> R["Lokales Codex: suchen, abrufen, auflisten oder sicher löschen"]
K --> S["Vorbereiteter gehosteter MCP: GitHub-Lesezugriff"]
S --> T["ChatGPT nach Bereitstellung und Prüfung"]
K --> U["iOS: lokaler Cache und Volltextsuche"]
U --> V["Beiträge und PDFs lesen; optionaler Chat auf dem Gerät"]
```

Der Ablauf im Einzelnen:
Expand Down Expand Up @@ -87,6 +91,9 @@ Der Ablauf im Einzelnen:
bleibt der zuletzt synchronisierte Index lesbar. Der vorbereitete
ChatGPT-Dienst sucht und liest über GitHub, nennt Suchgrenzen ausdrücklich
und bietet weder lokalen Index noch Löschwerkzeuge.
Die iOS-App liest heruntergeladene Beiträge offline, durchsucht deren Text
und bietet auf unterstützten Geräten optionalen Apple-Intelligence-Chat mit
Quellenlinks.

Die Trennung zwischen GitHub-Archiv und lokalem Such-Cache ist für größere
Sammlungen entscheidend: Auch bei vielen Tausend Dokumenten muss eine normale
Expand Down Expand Up @@ -246,8 +253,8 @@ Gist-Tab mit aktiver GitHub-Sitzung geladen werden.

## Chrome-Installation aus dem Quellcode

Bis der Eintrag im Chrome Web Store live ist, lässt sich die geprüfte
Erweiterung aus diesem Checkout laden:
Chrome-Version **1.1.0** ist für die Einreichung im Chrome Web Store vorbereitet.
Bis der Eintrag live ist, lässt sich die Erweiterung aus diesem Checkout laden:

1. `chrome://extensions` öffnen.
2. **Entwicklermodus** aktivieren.
Expand Down Expand Up @@ -290,7 +297,7 @@ Datei bereit. Sie lässt sich lokal so bauen:

```bash
python3 scripts/build_setup_package.py
python3 dist/sourcebraid-github-setup-v1.0.1.py --help
python3 dist/sourcebraid-github-setup-v1.1.0.py --help
```

## GitHub-Token
Expand Down Expand Up @@ -318,13 +325,20 @@ Optionale API-Einstellungen:

## SourceBraid in ChatGPT und Codex

Die primäre ChatGPT-Veröffentlichung nutzt den gehosteten MCP-Dienst unter
Die vorbereitete ChatGPT-Version **1.1.0** nutzt den gehosteten MCP-Dienst unter
[`chatgpt-mcp/`](chatgpt-mcp/). Vorgesehener Endpunkt ist
`https://mcp.sourcebraid.com/mcp`; Bereitstellung, Live-Authentifizierungstests
und OpenAI-Prüfung samt Veröffentlichung stehen noch aus. Die Schritte stehen
in der [Bereitstellungsanleitung](docs/CHATGPT_MCP_DEPLOYMENT.md) und im
[OpenAI-MCP-Einreichungskit](marketing/OPENAI_MCP_SUBMISSION.md).

Das Release-Bundle enthält `sourcebraid-chatgpt-plugin-v1.1.0.zip` für den Upload
im OpenAI-Plugin-Portal. Es enthält Plugin-Metadaten, die Remote-MCP-Konfiguration
und das Listing-Icon. `sourcebraid-chatgpt-mcp-v1.1.0.zip` enthält den
Worker-Quellcode zur Bereitstellung. Beide entstehen mit
`python3 scripts/build_release.py`; der Paketbau stellt keinen Dienst bereit
und veröffentlicht keinen Eintrag.

Nach Bereitstellung verbinden sich Nutzer über die HTTPS-Zustimmungsseite von
SourceBraid mit einem Fine-grained-GitHub-Token: **Contents: Read-only** für
genau ein privates Archiv-Repository. Der Token gehört niemals in einen
Expand All @@ -334,8 +348,8 @@ indexieren. Die Suche auf dem Standardbranch nutzt GitHub Code Search und
prüft Treffer an einem festgehaltenen Commit. Indexierungsverzögerungen,
Suchgrenzen und ein gegebenenfalls begrenzter Fallback werden ausgewiesen.

Das lokale Codex-Plugin bleibt die Variante mit voller Archivverwaltung. Es
benötigt Python 3 und lokale GitHub-Authentifizierung. Ein reines Skills-ZIP
Das lokale Codex-Plugin **1.1.0** bleibt die Variante mit voller Archivverwaltung.
Es benötigt Python 3 und lokale GitHub-Authentifizierung. Ein reines Skills-ZIP
verschafft gewöhnlichem ChatGPT allein keinen Zugriff auf lokale Dateien oder
Zugangsdaten.

Expand All @@ -347,12 +361,12 @@ codex plugin marketplace add .
codex plugin add sourcebraid@sourcebraid
```

Sobald der geprüfte Tag `v1.0.1` veröffentlicht ist, lautet die an diesen Tag
Sobald der geprüfte Tag `v1.1.0` veröffentlicht ist, lautet die an diesen Tag
gebundene Installation von GitHub:

```bash
codex plugin marketplace add patrickschiller/sourcebraid \
--ref v1.0.1 \
--ref v1.1.0 \
--sparse .agents/plugins \
--sparse codex-plugin/sourcebraid
codex plugin add sourcebraid@sourcebraid
Expand Down Expand Up @@ -394,7 +408,7 @@ Der Index liegt getrennt pro Repository, Branch und Archivordner unter
Eine Suche prüft höchstens alle 15 Minuten, ob sich der Remote-Head geändert
hat; wenn GitHub nicht erreichbar ist, bleibt der lokale Index nutzbar.
`search --scan` ist ein expliziter Diagnose-Fallback auf Basis von `rg`.
Der sicherere Cache-Pfad dieser Version löst einen erneuten Erstaufbau aus;
Bei einem älteren Cache-Layout wird der Index im aktuellen Cache-Pfad neu aufgebaut;
Markdown-Dateien und Git-Historie bleiben unverändert.

Neue Captures schreiben stabile URL-Hash-Shards wie
Expand Down Expand Up @@ -429,13 +443,19 @@ Nach einmaliger Einrichtung von Repository und Token können URLs, ausgewählter
Text, Safari-Artikel mit relevanten Bild-Assets, PDFs und andere Dateien über
das Teilen-Menü an das konfigurierte private Archiv gesendet werden.

Der iOS-Release-Kandidat **1.1.0** ergänzt einen Markdown-Reader, die neuesten
sieben Beiträge, Offline-Downloads und Volltextsuche, optionalen lokalen
Apple-Intelligence-Chat mit Quellenlinks sowie adaptive iPad-/iPhone-Duo-Navigation.
Der Maintainer hat die Veröffentlichung nach einem eigenen Funktionstest am
15. Oktober 2026 freigegeben. Xcode-Cloud-Distribution und App-Store-Verfügbarkeit
werden getrennt verfolgt; die Freigabe belegt keinen erfolgreichen Cloud-Build
oder Store-Release. Siehe [Release-Hinweise 1.1.0](docs/IOS_RELEASE_1.1.0.de.md),
Der Maintainer hat am 15. Oktober 2026 bestätigt, dass iOS **1.1.0** im App Store
veröffentlicht ist. Die Version ergänzt einen Markdown-Reader, die neuesten
sieben Beiträge, Offline-Downloads und Volltextsuche, native PDF-Vorschauen,
optionalen lokalen Apple-Intelligence-Chat mit Quellenlinks, schreibgeschützte
App-Kurzbefehle sowie adaptive iPad-/iPhone-Duo-Navigation.

Reader und Suche unterstützen iOS/iPadOS ab 17. Chat benötigt zusätzlich
iOS/iPadOS ab 26, unterstützte Hardware, aktivierte Apple Intelligence und ein
verfügbares Systemmodell in einer unterstützten Sprache. Die Suche erfasst
heruntergeladene Texte; anfangs kann die Archivabdeckung unvollständig sein.
iOS bestimmt die Hintergrund-Ausführungszeit. Die Veröffentlichung erklärt
die verbleibenden Geräteprüfungen nicht für bestanden.
Siehe [Release-Hinweise 1.1.0](docs/IOS_RELEASE_1.1.0.de.md),
[Umsetzungs- und Testprotokoll](docs/IOS_IMPLEMENTATION_TESTING.de.md)
und [verbleibende Geräteprüfungen](docs/IOS_DEVICE_ACCEPTANCE.de.md). Native
Navigation für Neueste/Suche/Chat und begrenzte Hintergrundaktualisierung stehen
Expand Down
57 changes: 37 additions & 20 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,14 +18,15 @@ you with ordinary files and Git history that remain useful without SourceBraid.
## How SourceBraid works

SourceBraid combines capture clients, a private GitHub repository as the durable
source of truth, and two archive-access paths. The local Codex plugin supports
search and archive management. The hosted, read-only ChatGPT integration is
prepared for deployment and review; it is not yet a live public service. The
source of truth, and three archive-access paths. The iOS app provides a local
reader, offline search, and optional on-device chat. The local Codex plugin
supports search and archive management. The hosted, read-only ChatGPT integration
is prepared for deployment and review; it is not yet a live public service. The
Chrome extension and iOS app write captures directly to the configured GitHub
repository. Hosted ChatGPT requests will pass through SourceBraid's Cloudflare
Worker without creating a permanent content database.

The local SQLite index is only a rebuildable search cache. Markdown files and
Local SQLite indexes are only rebuildable search caches. Markdown files and
Git history remain authoritative.

```mermaid
Expand Down Expand Up @@ -53,6 +54,8 @@ flowchart TD
Q --> R["Local Codex: search, fetch, list, or safely delete"]
K --> S["Prepared hosted MCP: read-only GitHub access"]
S --> T["ChatGPT after deployment and review"]
K --> U["iOS: local cache and full-text search"]
U --> V["Read clips and PDFs; optional on-device chat"]
```

The workflow in detail:
Expand All @@ -79,6 +82,8 @@ The workflow in detail:
when GitHub is unavailable. The prepared ChatGPT service searches and fetches
through GitHub with read-only access, explicit coverage limits, and no local
index or deletion tools.
The iOS app reads downloaded clips offline, searches their cached text, and
offers optional Apple Intelligence chat with source links on supported devices.

Keeping the GitHub archive separate from the local search cache matters for
large collections: a normal query does not need to reopen thousands of Markdown
Expand Down Expand Up @@ -225,8 +230,8 @@ be loaded through the still-open Gist tab.

## Chrome installation from source

Until the Chrome Web Store listing is live, load the reviewed extension from
this checkout:
Chrome version **1.1.0** is prepared for Chrome Web Store submission. Until the
listing is live, load the extension from this checkout:

1. Open `chrome://extensions`.
2. Enable **Developer mode**.
Expand Down Expand Up @@ -266,7 +271,7 @@ locally with:

```bash
python3 scripts/build_setup_package.py
python3 dist/sourcebraid-github-setup-v1.0.1.py --help
python3 dist/sourcebraid-github-setup-v1.1.0.py --help
```

## GitHub token
Expand All @@ -293,12 +298,19 @@ Optional API configuration:

## SourceBraid in ChatGPT and Codex

The primary ChatGPT release uses the hosted MCP service in [`chatgpt-mcp/`](chatgpt-mcp/).
The prepared **1.1.0** ChatGPT release uses the hosted MCP service in
[`chatgpt-mcp/`](chatgpt-mcp/).
Its intended endpoint is `https://mcp.sourcebraid.com/mcp`; deployment, live
authentication tests, and OpenAI review/publication are still required. Follow
the [deployment guide](docs/CHATGPT_MCP_DEPLOYMENT.md) and
[OpenAI MCP submission kit](marketing/OPENAI_MCP_SUBMISSION.md).

The release bundle includes `sourcebraid-chatgpt-plugin-v1.1.0.zip` for upload
to OpenAI's plugin portal. It contains the plugin metadata, remote MCP
configuration, and listing icon. `sourcebraid-chatgpt-mcp-v1.1.0.zip` contains
the Worker source for deployment. Build both with `python3 scripts/build_release.py`;
building the files does not deploy the service or publish a listing.

After the service is deployed, users connect through SourceBraid's HTTPS consent
page using a fine-grained GitHub token with **Contents: Read-only** for exactly
one private archive repository. Never paste that token into a ChatGPT prompt.
Expand All @@ -307,8 +319,8 @@ edit, delete, migrate metadata, or build a local index. Default-branch search
uses GitHub Code Search and verifies matches at a pinned commit. Indexing delays,
limits, and any bounded fallback are reported with the results.

The local Codex plugin remains the full archive-management option. It needs
Python 3 and local GitHub authentication; a skills-only ZIP does not by itself
The local Codex plugin **1.1.0** remains the full archive-management option. It
needs Python 3 and local GitHub authentication; a skills-only ZIP does not by itself
give ordinary ChatGPT access to those local files or credentials.

For local development, add this checkout as a marketplace and install the
Expand All @@ -319,12 +331,12 @@ codex plugin marketplace add .
codex plugin add sourcebraid@sourcebraid
```

After the reviewed `v1.0.1` tag is published, the tag-bound GitHub installation
After the reviewed `v1.1.0` tag is published, the tag-bound GitHub installation
is:

```bash
codex plugin marketplace add patrickschiller/sourcebraid \
--ref v1.0.1 \
--ref v1.1.0 \
--sparse .agents/plugins \
--sparse codex-plugin/sourcebraid
codex plugin add sourcebraid@sourcebraid
Expand Down Expand Up @@ -364,8 +376,8 @@ The index is stored separately per repository, branch, and archive root under
for a changed remote head at most every 15 minutes; when GitHub is unavailable,
the local index remains usable. `search --scan` is an explicit `rg` diagnostic
fallback.
The safer cache namespace introduced in this release triggers a fresh initial
build; existing Markdown and Git history are unchanged.
Archives with an older cache layout receive a fresh initial index build in the
current cache namespace; existing Markdown and Git history are unchanged.

New captures write stable URL-hash shards such as
`web-clips/index/47.jsonl`. Legacy archives remain readable. Preview and confirm
Expand Down Expand Up @@ -395,12 +407,17 @@ After one-time repository and token setup, URLs, selected text, Safari articles
with relevant image assets, PDFs, and other files can be sent to the configured
private archive through the system share sheet.

The iOS **1.1.0** release candidate adds a Markdown reader, the latest seven
clips, offline downloads and full-text search, optional on-device Apple
Intelligence chat with source links, and adaptive iPad/iPhone Duo navigation.
The maintainer approved publication after a hands-on functional check on
October 15, 2026. Xcode Cloud distribution and App Store availability are tracked
separately; approval does not establish a successful cloud build or store release.
The maintainer confirmed on October 15, 2026 that iOS **1.1.0** is published
in the App Store. It adds a Markdown reader, the latest seven clips, offline
downloads and full-text search, native PDF previews, optional on-device Apple
Intelligence chat with source links, read-only App Shortcuts, and adaptive
iPad/iPhone Duo navigation.

Reader and search support iOS/iPadOS 17 or later. Chat additionally requires
iOS/iPadOS 26 or later, supported hardware, enabled Apple Intelligence, and an
available system model in a supported language. Search covers downloaded text;
initial archive coverage can be partial. Background refresh remains subject to
iOS scheduling. Publication does not mark the remaining device checks as passed.
See the [1.1.0 release notes](docs/IOS_RELEASE_1.1.0.md),
[implementation and test record](docs/IOS_IMPLEMENTATION_TESTING.md), and
[remaining device checks](docs/IOS_DEVICE_ACCEPTANCE.md). Native
Expand Down
Loading
Loading