Stop Context7 serving anti-pattern samples; collapse three doc copies into one

.github/pull_request_template.md

@@ -8,8 +8,8 @@ Full reviewer guide: REVIEW.md
 ## Type
 
 - [ ] Docs refresh (automated, opened by `refresh-docs.yml`)
-- [ ] Manual polished-content edit
-- [ ] Pipeline / schema / CI / skill change
+- [ ] Manual reference-content edit
+- [ ] Skill / pipeline / CI change
 
 ---
 
@@ -19,35 +19,33 @@ Full reviewer guide: REVIEW.md
 
 Reviewer checklist (see [`REVIEW.md`](../REVIEW.md) for the full version):
 
-- [ ] Source diff looks sane; `source_ref` is a commit SHA, not a branch
-- [ ] `pnpm snapshot:refresh` committed
+- [ ] `source_ref` is a commit SHA, not a branch; the `source.ref` bump matches the docs commit in the body
 - [ ] `pnpm check:all` green locally
-- [ ] Corpus diff read against `sources/`: the transform only reshaped (boilerplate stripped, callouts converted) — no content added, weakened, or reversed
+- [ ] **Changed guidance still agrees with `PITFALLS.md`** — if the docs now contradict a pitfall, resolve it in this PR
+- [ ] If a referenced heading moved, `SKILL.md`'s routing table updated to match
+- [ ] Diff read as documentation: the transform only reshaped (boilerplate stripped, callouts converted) — no content added, weakened, or reversed
 - [ ] Upstream snippet bugs (if any) tracked as separate issues against `Iterable/iterable-docs` — **not** hand-fixed here
 
 ---
 
-## If this is a manual polished-content edit
+## If this is a manual reference-content edit
 
 Why is the deterministic transform insufficient for this change? (One sentence.)
 
 <!-- e.g. "Foreign-language stripping of a cross-platform doc — the transform
 doesn't do this yet." -->
 
-- [ ] `pnpm recompute:manifest` run for every edited corpus file
-- [ ] `pnpm snapshot:refresh` committed
 - [ ] `pnpm check:all` green locally
 - [ ] Considered whether the transform (`pipeline/src/lib/layer-a.ts`) could be updated instead of editing by hand
+- [ ] Noted that the next `pnpm refresh:docs` will overwrite this file if upstream changes
 
 ---
 
-## If this is a pipeline / schema / CI / skill change
+## If this is a skill / pipeline / CI change
 
-- [ ] `pnpm typecheck` green
 - [ ] `pnpm check:all` green
 - [ ] If changing the schema or a validator, tested both the success and the failure case locally
-- [ ] If changing `iterable-android/SKILL.md`, sanity-checked the routing table against `polished/<platform>/`
-- [ ] If changing the snippet manifest format, ran `pnpm recompute:manifest polished/**/*.polished.md` and confirmed no semantic drift
+- [ ] If changing `iterable-android/SKILL.md`, sanity-checked the routing table against `iterable-android/reference/`
 
 ---
 

.github/workflows/refresh-docs.yml

@@ -3,11 +3,10 @@ name: Refresh docs
 # Triggered when Iterable/iterable-docs publishes a change to an SDK doc
 # path. The docs repo dispatches `iterable-docs-changed` (optionally with a
 # `client_payload.ref` = the docs commit); this workflow resolves that ref
-# (or the docs default-branch head on a manual run), fetches the fresh
-# markdown at that commit, runs the deterministic transform, bumps the
-# pinned `source.ref` in pipeline/config to match, and opens a PR. There is
-# no LLM step — the corpus is the docs reshaped. A reviewer refreshes the
-# snapshot and merges.
+# (or the docs default-branch head on a manual run), rewrites
+# `iterable-android/reference/` from the docs at that commit, bumps the pinned
+# `source.ref` in pipeline/config to match, and opens a PR. There is no LLM
+# step — the corpus is the docs reshaped.
 #
 # `workflow_dispatch` is kept as a manual fallback for re-running a
 # refresh outside of a docs-side trigger (e.g. when validating a config
@@ -77,28 +76,24 @@ jobs:
           echo "label=master @ $(date -u +%Y-%m-%d)" >> "$GITHUB_OUTPUT"
           echo "Resolved ${req} → ${sha}"
 
-      - name: Fetch sources (reads private iterable-docs via gh api)
+      - name: Refresh reference corpus (reads private iterable-docs via gh api)
         working-directory: pipeline
         env:
           GH_TOKEN: ${{ secrets.DOCS_READ_TOKEN }}
           SOURCE_REF: ${{ steps.ref.outputs.sha }}
-        run: pnpm fetch:sources -- ${{ github.event.inputs.platform || github.event.client_payload.platform || 'android' }}
-
-      - name: Polish Layer A
-        working-directory: pipeline
-        run: pnpm polish:a -- --platform=${{ github.event.inputs.platform || github.event.client_payload.platform || 'android' }}
+        run: pnpm refresh:docs -- ${{ github.event.inputs.platform || github.event.client_payload.platform || 'android' }}
 
       - name: Detect changes
         id: changes
         run: |
-          if git diff --quiet sources/ polished/; then
+          ref_dir=iterable-android/reference
+          if git diff --quiet "$ref_dir"; then
             echo "changed=false" >> "$GITHUB_OUTPUT"
             exit 0
           fi
           echo "changed=true" >> "$GITHUB_OUTPUT"
-          # Slugs touched in sources/ this run
-          slugs=$(git diff --name-only sources/ \
-            | sed -E 's|sources/[^/]+/([^/]+)\.md|\1|' \
+          slugs=$(git diff --name-only "$ref_dir" \
+            | sed -E "s|.*/([^/]+)\.md|\1|" \
             | sort -u | paste -sd ', ' -)
           echo "slugs=${slugs}" >> "$GITHUB_OUTPUT"
 
@@ -111,13 +106,6 @@ jobs:
           ${{ steps.ref.outputs.sha }}
           "${{ steps.ref.outputs.label }}"
 
-      - name: Refresh snapshot
-        if: steps.changes.outputs.changed == 'true'
-        working-directory: pipeline
-        # polish:a wrote the fresh corpus to polished/; the snapshot must be
-        # regenerated from it or the PR fails its own snapshot:verify gate.
-        run: pnpm snapshot:refresh
-
       - name: Open refresh PR
         if: steps.changes.outputs.changed == 'true'
         uses: peter-evans/create-pull-request@v6
@@ -132,28 +120,26 @@ jobs:
 
             Slugs: ${{ steps.changes.outputs.slugs }}
           body: |
-            Automated refresh of `sources/` and the deterministic `polished/`
-            corpus (Layer A). **No LLM rewrite step** — the polished corpus is
-            a deterministic transform of the docs.
+            Automated refresh of `iterable-android/reference/` — the docs corpus
+            the skill reads. **No LLM step**: the corpus is a deterministic
+            transform of Iterable's published docs.
 
             **Slugs touched:** ${{ steps.changes.outputs.slugs }}
             **Docs commit:** `${{ steps.ref.outputs.sha }}`
             (`source.ref` in `pipeline/config` is bumped to this in the diff).
 
             ## Reviewer steps
 
-            1. Check out this branch.
-            2. Spot-check the diff against `sources/` for content fidelity —
-               the transform only strips boilerplate / normalizes structure,
-               so headings and code should match the upstream docs.
+            1. Read the diff as docs, not code — this is what the agent will
+               tell developers to do. Check that changed guidance still agrees
+               with `iterable-android/PITFALLS.md`; if the docs now contradict a
+               pitfall, the pitfall needs updating in the same PR.
+            2. If a slug's headings moved, check the routing table in
+               `iterable-android/SKILL.md` still points at sections that exist.
             3. Confirm the `source.ref` bump in `pipeline/config` matches the
                docs commit above (provenance stays honest).
-            4. Run `pnpm snapshot:refresh` and commit the resulting
-               `iterable-android/snapshot/` changes. CI's `snapshot:verify`
-               gate will fail the build otherwise.
-            5. Confirm `pnpm check:all` is green locally.
-            6. Merge to `main`. Context7 picks up the change on its next
-               crawl (`context7.json` controls scope).
+            4. Merge to `main`. Context7 re-indexes on its next crawl
+               (`context7.json` controls scope).
           labels: |
             docs-refresh
             automated

.github/workflows/validate.yml

@@ -1,27 +1,30 @@
-name: Validate polished corpus
+name: Validate
 
-# Runs the pipeline's full validation suite on every push to main and every PR.
-# Blocking gates: typecheck, polished-frontmatter schema, layer-a vs polished
-# structural diff. Advisory (always exit 0): chunking lint and kotlinc snippet
-# check. The snippet check is advisory in v1 because kotlinc -script runs full
-# semantic analysis and floods on "unresolved reference" without a classpath;
-# tracked follow-up loads the Iterable SDK + android.jar so it can become
-# blocking in v2.
+# Blocking gates only: typecheck, reference-corpus frontmatter + config/corpus
+# slug agreement, and plugin manifests. Every gate here can actually fail.
 
 on:
   push:
     branches: [main]
     paths:
-      - polished/**
+      - iterable-android/**
       - pipeline/**
-      - iterable-android/snapshot/**
+      - .claude-plugin/**
+      - .cursor-plugin/**
+      - mcp.json
+      - .mcp.json
+      - context7.json
       - .github/workflows/validate.yml
   pull_request:
     branches: [main]
     paths:
-      - polished/**
+      - iterable-android/**
       - pipeline/**
-      - iterable-android/snapshot/**
+      - .claude-plugin/**
+      - .cursor-plugin/**
+      - mcp.json
+      - .mcp.json
+      - context7.json
       - .github/workflows/validate.yml
   workflow_dispatch:
 
@@ -48,22 +51,6 @@ jobs:
           cache: pnpm
           cache-dependency-path: pipeline/pnpm-lock.yaml
 
-      - name: Setup Java (kotlinc dependency)
-        uses: actions/setup-java@v4
-        with:
-          distribution: temurin
-          java-version: "17"
-
-      - name: Install Kotlin compiler
-        run: |
-          set -euo pipefail
-          curl -sL "https://github.com/JetBrains/kotlin/releases/download/v1.9.24/kotlin-compiler-1.9.24.zip" -o /tmp/kotlinc.zip
-          unzip -q /tmp/kotlinc.zip -d "$HOME"
-          echo "$HOME/kotlinc/bin" >> "$GITHUB_PATH"
-
-      - name: Verify kotlinc
-        run: kotlinc -version
-
       - name: Install pipeline deps
         working-directory: pipeline
         run: pnpm install --frozen-lockfile