From 9f4120066d407fd5f326f3ac2eac0b33c28b74bd Mon Sep 17 00:00:00 2001 From: Franco Zalamena Date: Thu, 23 Jul 2026 11:42:18 +0100 Subject: [PATCH] Enable live Context7 fetching (snapshot becomes fallback) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Iterable's curated library is published and verified on Context7 (/iterable/iterable-sdk-skill — 730 snippets, live). Flip the skill from "snapshot authoritative, don't fetch Context7" to "Context7-first, snapshot as offline fallback." All four coupled spots move together (a partial flip is the known failure mode): - .context7-library-id: replace TODO-PHASE-3 placeholder with the real ID, drop the placeholder status block. - SKILL.md "How to use this skill": Context7 is the authoritative source (read ID → query-docs one doc per slug); snapshot is the offline fallback. - SKILL.md decision-flow step 3 + "start here" pointer: match the new source priority. - README "How it works" + Limitations: fetches live from Context7, snapshot as fallback; remove the "not live yet" limitation. Co-Authored-By: Claude Opus 4.8 --- README.md | 21 ++++++------- iterable-android/.context7-library-id | 10 ++---- iterable-android/SKILL.md | 45 +++++++++++++-------------- 3 files changed, 35 insertions(+), 41 deletions(-) diff --git a/README.md b/README.md index 9cb49cd..2e5db13 100644 --- a/README.md +++ b/README.md @@ -40,16 +40,17 @@ tasks (see [How it works](#how-it-works)). ## How it works -The skill carries a copy of the Iterable documentation inside it -(`iterable-android/snapshot/`), so it always has the docs on hand — even offline. -This snapshot is the active source today. - -The plugin (both Claude Code and Cursor) also connects to +The skill fetches Iterable's documentation live from [Context7](https://context7.com), a service that hosts docs for AI assistants to -query on demand. That connection is bundled and ready, but stays dormant until -Iterable's curated library is published there; once it is, the skill fetches the -latest docs live, with the snapshot as its fallback. No reinstall needed when -that happens. +query on demand. Iterable's curated library is published there +([`/iterable/iterable-sdk-skill`](https://context7.com/iterable/iterable-sdk-skill)), +and the plugin (both Claude Code and Cursor) bundles the connection to it, so the +assistant always pulls the latest vetted snippets for whatever feature you're on. + +The skill also carries a byte-for-byte copy of that corpus inside it +(`iterable-android/snapshot/`) as an offline fallback — if Context7 is +unreachable, it reads from the snapshot instead, so the skill still works with no +network. > Context7 works without an API key at a lower rate limit, which is how the > bundled config ships. To raise the limit, get a free key at @@ -92,5 +93,3 @@ See [`REVIEW.md`](REVIEW.md). - **Android only.** iOS, React Native, and Web are not yet covered. - **Some docs carry foreign snippets.** A few articles come from shared "Mobile SDKs" pages and still contain iOS/JS code an Android agent must ignore. -- **Context7 fetch is not live yet.** The skill works today from its bundled - snapshot; on-demand Context7 fetching turns on in an upcoming release. diff --git a/iterable-android/.context7-library-id b/iterable-android/.context7-library-id index d98b985..92f91a0 100644 --- a/iterable-android/.context7-library-id +++ b/iterable-android/.context7-library-id @@ -1,14 +1,10 @@ # Context7 library ID for this skill — single source of truth. # # SKILL.md references this file by path so a future org migration -# (franco-zalamena-iterable -> Iterable) is a one-line PR here, not a -# coordinated rewrite across SKILL.md, README.md, and downstream agents. +# is a one-line PR here, not a coordinated rewrite across SKILL.md, +# README.md, and downstream agents. # # Format: one library ID per line, comments allowed (lines starting with #). # The first non-comment, non-empty line is canonical. -# -# Status: PLACEHOLDER until Phase 3 completes — see TODO below. -# After context7.com/add-library returns a library ID, replace the line below -# with the real value and remove this status block. -TODO-PHASE-3/iterable-sdk-skill +/iterable/iterable-sdk-skill diff --git a/iterable-android/SKILL.md b/iterable-android/SKILL.md index 4fa9f06..c67b7dd 100644 --- a/iterable-android/SKILL.md +++ b/iterable-android/SKILL.md @@ -281,7 +281,8 @@ override fun onCreate() { ``` The full per-feature docs (push, in-app, inbox, embedded, deep links, events, -profiles, UUA) are in the snapshot — see the routing table below. +profiles, UUA) come from Context7, with the local snapshot as offline fallback — +see the routing table below. --- @@ -292,28 +293,26 @@ Task-specific guidance (push, in-app, inbox, embedded, JWT, deep links, event tracking, user profiles, UUA, initialization) lives in a polished corpus. -### Source today: the local snapshot (authoritative) +### Source today: Context7 (authoritative) -**Read task docs from [`snapshot/`](snapshot/).** It's a byte-for-byte mirror -of the polished corpus at last release, kept honest by CI (`pnpm -snapshot:verify`). Match the task to a slug (table below) and open -`snapshot/.md`. This is the canonical source right now — don't try -Context7 first. +**Fetch task docs from Context7.** Iterable's curated library is published and +live: the ID is in [`.context7-library-id`](.context7-library-id) (first +non-comment line — currently `/iterable/iterable-sdk-skill`). The Context7 MCP +server is connected (the plugin bundles it). The flow: read the ID from that +file, match the task to a slug (table below), fetch that one doc via the +Context7 MCP `query-docs` tool (self-contained — one doc per task, don't +bulk-load), use its snippets verbatim, and surface any `sdk_min_version` +mismatch. You don't need `resolve-library-id` — the ID is known; pass it +straight to `query-docs`. -### Source later: Context7 *(curated library not published yet — do not fetch)* +### Fallback: the local snapshot -The Context7 MCP server **is** connected (the plugin bundles it), but Iterable's -curated library is **not published there yet** — [`.context7-library-id`](.context7-library-id) -is still the placeholder `TODO-PHASE-3/...`. So do **not** call Context7 for -Iterable docs right now: a `resolve-library-id` / `query-docs` lookup would -return some *unrelated public* library, not this skill's vetted corpus. The -[`snapshot/`](snapshot/) is authoritative until the real ID lands. - -Once a real library ID is dropped into that file (first non-comment line; one -that does **not** start with `TODO-`), the flow becomes: read the ID, fetch the -matching slug via the Context7 MCP tool (self-contained — one doc per task, -don't bulk-load), use its snippets verbatim, and surface any `sdk_min_version` -mismatch. +If Context7 is unreachable (offline, MCP not connected, rate-limited), read from +[`snapshot/`](snapshot/) instead. It's a byte-for-byte mirror of the polished +corpus at last release, kept honest by CI (`pnpm snapshot:verify`) — match the +task to a slug and open `snapshot/.md`. The snapshot may lag Context7 +between releases, so prefer Context7 when it's available; the snapshot exists so +the skill still works with no network. ### Slug routing @@ -354,9 +353,9 @@ order. 2. **Check rules 1–5 above** against whatever the user already has. Many "the SDK isn't working" reports are rule violations. 3. **Read the matching slug for the task** before writing code, from whichever - source the "How to use this skill" section marks authoritative (the - `snapshot/` today). Each doc has its own gotchas section that supersedes - generic advice. + source the "How to use this skill" section marks authoritative (Context7, + with the `snapshot/` as offline fallback). Each doc has its own gotchas + section that supersedes generic advice. 4. **For non-obvious traps not covered in the polished doc**, consult [`PITFALLS.md`](PITFALLS.md). 5. **Version-check.** If the user is on an older SDK version than the doc's