# Session snapshot — 2026-05-18

Built the **Patent Client Index** (working name): the published, opinionated
atlas of patent + IP data sources. Atlas page + map at
`patentclient.com/atlas`, deep-dive synopsis pages at
`docs.patentclient.com/patent-client-index/`. Unified data layer
(`coverage/atlas.json`) feeds both. Cross-links both ways.

This doc captures what landed, the policies that emerged, and what's
queued for the next session.

---

## §1 What landed (by area)

### Data layer (`patent-client-agents`)
- **`coverage/atlas.json`** — new build artifact, office-centric fusion of
  `research/STATE.yaml` + `coverage/sources.yaml`. 46 entities, 9
  unattached sources. Schema documented in
  [`ATLAS_INTEGRATION.md`](ATLAS_INTEGRATION.md) §3.
- **`scripts/build_coverage.py`** — extended with `build_atlas_payload()`,
  `build_atlas_entities()`, `compute_atlas_summary()`, region mapping,
  shipped-source-to-entity prefix matching.
- **`coverage/coverage.json`** — still emitted (back-compat for legacy
  consumers); shape unchanged.
- **`.github/workflows/ci.yml`** — added `coverage-manifest` job that
  runs `build_coverage.py --check` on every PR.

### Atlas viz (`patentclient-web`)
- **`atlas.html`** — new page. Hero strip (title + lede) → big world
  map → legend strip below the map → compact filter bar → card grid.
- **`assets/atlas.js`** (~470 lines, vanilla ESM) — D3 map colored by
  rating, faceted filters with live counts, drawer with verdict basis +
  deep-link, ?focus=ISO2 deep-linking, localhost rewrite for local dev.
- **`assets/atlas.css`** — full styling, light + dark modes.
- **`_redirects`** — `/coverage` → `/atlas` (301 alias).
- **`sitemap.xml`** — added `/atlas` URL.
- **`index.html`** nav → `/atlas`.

### Docs deep dives (`patent-client-agents/docs_hooks/`)
- **`sync_patent_client_index.py`** — mkdocs hook that virtual-mounts
  every `research/{multilateral,regional,national}/*.md` synopsis under
  the `Patent Client Index` tab. Transforms at render time:
  - Frontmatter ` **Label:** value` lines → markdown infobox table
  - `**Label:**` + bullet-list blocks → proper paragraph + `<ul>`
    (FIX-15 & FIX-18 — applies to whole body, not just frontmatter)
  - §5 `Connector strategy` → §5 `Access via patent-client-agents`
  - §6 `Open questions` → §6 `Known unknowns`
  - §8 change log → "Last updated YYYY-MM-DD." footer
  - Cross-refs (`../connectors/X.md`, `../../coverage/sources.yaml`,
    etc.) resolved via `posixpath.normpath` to clean GitHub URLs (no
    literal `..` segments)
  - Verdict callout prepended after frontmatter, with `?focus=` link
    back to the atlas map
- **`docs/stylesheets/extra.css`** — added the infobox-table treatment
  for `article > table:first-of-type`.
- **`mkdocs.yml`** — added the `Patent Client Index` nav tab + the
  hook reference.

### Source synopses (`research/`)
- **Heading set normalized across all 17 synopsis files** (FIX-19):
  ```
  §1 Mission
  §2 What's unique here
  §3 Programmatic surfaces
  §4 Fees                                  ← was "Fee schedule"; canonicalized
  §5 Connector strategy                     ← source name; published as "Access via patent-client-agents"
  §6 Open questions                          ← source name; published as "Known unknowns"
  §7 References
  §8 Change log                              ← collapsed to footer in publish
  ```
- **All inline fee tables stripped** (FIX-16, FIX-17). §4 is now
  link-only across all 12 affected files. See policy below.
- **`research/fee-schedules/` directory deleted** along with every
  reference to it across STATE.yaml, synopses, RUNBOOK, PIPELINE,
  COVERAGE_STRATEGY, BACKLOG, specs/README, atlas.json schema.
- **`verdict` → `rating` across the entire codebase** (FIX-11). YAML
  field names, atlas.json keys, hook constants, atlas.js variables,
  CSS class names, data attributes — all migrated.
- **STATE.yaml** — `verdict:` → `rating:`, `verdict_basis:` →
  `rating_basis:`, `fee_research:` field removed entirely, header
  docstring updated.

### Atlas viz polish
- Map at the top (FIX-8), legend below the map (FIX-9), section
  headings reframed without "verdict" (FIX-9).
- Cards compact + sorted by rating color green→yellow→red→tbd→
  untracked (FIX-13).
- Per-card "Deep dive →" link, plus working drawer button (FIX-14).
- Local-dev URL rewrite: `docs.patentclient.com` → `localhost:8766`
  when atlas.html is served from `localhost`.

---

## §2 Policies established

### Fees — link only, never mirror
- Synopsis §4 describes **what categories** of fees an office charges
  (in local currency), lists **discount programs by name**, and links
  to the **official schedule URL**. That's it.
- **No inline amounts.** No percentages. No effective dates.
- The `research/fee-schedules/` directory was deleted entirely; we are
  not in the business of mirroring authoritative fee data — it drifts,
  the office's page is canonical at any moment, and reproducing it
  would lock us into a permanent re-research treadmill.
- The synopsis template (`research/templates/office-synopsis.md`) §4
  embeds the policy with `**Policy: link only. Reproducing fee
  amounts is *not our job*.**`
- The RUNBOOK §B is now an explicit "out of scope" notice.

### Substantive content drift discipline
- Synopses document **what information is available**, not the
  information itself.
- Citations to specific decisions (e.g., `CA/D 9/25`) in link labels
  are OK — they help readers navigate to the right notice. The
  substantive-data prohibition applies to inline numeric reproductions
  (amounts, percentages, effective dates) that would silently age out.
- Change log entries (§8) are historical decision records and stay; the
  hook collapses them to a "Last updated" footer in the published page.

### Vocabulary
- Public, user-facing word is **rating** (not "verdict" — litigation
  noun, out of place in IP).
- Color family: green, yellow, red, tbd, untracked. Each has a
  swatched legend entry.
- The hook keeps §-prefixes on renames so the rendered ToC reads
  continuously §1..§7. The verdict-callout anchor (now
  `#5-access-via-patent-client-agents`) updates in lockstep.

### Repo boundaries (unchanged — confirmed correct)
- `patent-client-agents` owns the **data** (research/, coverage/, mkdocs).
- `patentclient-web` owns the **interactive atlas** (D3 map, cards, drawer).
- jsDelivr CDN is the boundary between them. Both consume
  `coverage/atlas.json` and (legacy) `coverage/coverage.json`.

---

## §3 Architecture as it stands

```
research/STATE.yaml         ──┐  46 entities × {id, name, layer, iso2,
research/{layer}/*.md        ─┤  rights, rating, rating_basis,
coverage/sources.yaml        ─┤  connector_status, last_verified, ...}
                              ▼
                  scripts/build_coverage.py
                              │
                              ├──► coverage/coverage.json
                              │      • per-data-product view (40 sources)
                              │      • legacy /coverage page consumer
                              │
                              └──► coverage/atlas.json
                                     • per-office view (46 entities)
                                     • verdict + basis + synopsis_url
                                     • shipped_sources nested per office
                                     │
                                     │ jsDelivr CDN
                                     ▼
                       patentclient.com/atlas
                       ─ map colored by rating family
                       ─ 5-row legend strip
                       ─ compact 3-row filter bar
                       ─ card grid, sorted by color
                       ─ drawer with deep-link + GitHub fallback
                       ─ ?focus=ISO2 deep-link from docs side

docs_hooks/sync_patent_client_index.py
                              │
                              ▼
                docs.patentclient.com/patent-client-index/
                ─ §1 Mission · §2 What's unique here · §3 Programmatic surfaces
                ─ §4 Fees (link-only) · §5 Access via patent-client-agents
                ─ §6 Known unknowns · §7 References
                ─ Rating callout linked to atlas
```

---

## §4 Current freshness (audited 2026-05-18)

- **17 deep dives written**, all within 2 days of today
  (`2026-05-16` or `2026-05-17`). None stale.
- **29 entities without a synopsis** — split below.

Recent doc-policy refactors did **not** bump `last_verified`. That's
correct: `last_verified` tracks when we last checked the office's own
pages, not when we last reformatted our own writeup.

---

> **§5 has been superseded.** A later sub-session on 2026-05-18 (evening,
> UTC straddling into 2026-05-19) finished the §5 priority items and
> reshuffled the queue. The current queue is **§10** below; §5 is left
> in place as a historical record.

## §5 What's queued for the next session (HISTORICAL — see §10)

See [the freshness audit at end of this session]
([`SESSION-2026-05-18.md`](SESSION-2026-05-18.md) — i.e. this doc).
The priority stack is:

### Priority 1 — shipped without a synopsis (3)
| Entity | Connector | Why it's a gap |
|---|---|---|
| `US/USCO` | shipped | atlas drawer falls back to GitHub research |
| `UPC/UPC` | shipped | UPC decisions + UPC statutes both shipped |
| `WO/WIPO/Lex` | shipped | substantive-law backbone |

Closing these is mostly a writeup job — the connector code already
encodes the operational knowledge.

### Priority 2 — rated, in-progress, no synopsis (4)
- `BR/INPI` (yellow_paid)
- `SG/IPOS` (red_no_api)
- `IL/ILPO` (red_no_api)
- `RU/Rospatent` (red_blocked)

### Priority 3 — rated red regional, no synopsis (4)
Quick stubs to lock in the verdict; not full deep dives.
- `OA/OAPI`
- `AP/ARIPO`
- `GCC/GCCPatent`
- `RU/EAPO`

### Priority 4 — unresearched secondary nationals (17)
Queue a discovery wave (grouped by region) when there's a reason to
expand. From [`research/RUNBOOK-research.md`](research/RUNBOOK-research.md) §A.

`AT/OPA · CH/IPI · NL/RVO · SE/PRV · FI/PRH · ES/OEPM · IT/UIBM ·
MX/IMPI · AR/INPI · NZ/IPONZ · PH/IPOPHL · ID/DGIP · TH/DIP ·
ZA/CIPC · SA/SAIP · AE/IPO · TR/TURKPATENT`

---

## §6 Open items / known issues

- **`patent-client-index` is a placeholder name** — we agreed to keep
  it until we find a better one. Replacement is one global string
  swap when the time comes.
- **Production docs not yet redeployed** —
  `docs.patentclient.com/patent-client-index/...` returns 404 in
  production. Atlas cards' `Deep dive →` links work locally
  (rewritten to `localhost:8766`) but will need a CF Pages
  redeploy + a fresh build of the new docs tree before they work in
  production.
- **Atlas reads `coverage/atlas.json` from jsDelivr.** The CDN edge
  caches `@main` URLs for up to ~12 hours (the original "a few
  minutes" claim was wrong by an order of magnitude — confirmed
  2026-05-19 when atlas served 18-hour-stale data after a push).
  **After any push that touches `coverage/atlas.json`, manually
  purge the CDN:** `curl https://purge.jsdelivr.net/gh/parkerhancock/patent-client-agents@main/coverage/atlas.json`.
  See `ATLAS_INTEGRATION.md` §8 for the full deployment procedure.
  Local dev fetches a local copy (`patentclient-web/atlas.json`)
  to avoid CDN lag.
- **The dev-browser `__name is not defined` page error** is an
  instrumentation artifact, not a real bug. Confirmed it fires on
  `about:blank` too. Does not affect real browsers.

---

## §7 Documentation produced this session

| File | What it is |
|---|---|
| [`ATLAS_INTEGRATION.md`](ATLAS_INTEGRATION.md) | The integration plan doc (phase-by-phase TODO; now mostly done) |
| [`SESSION-2026-05-18.md`](SESSION-2026-05-18.md) | **This doc** — session snapshot + handoff |
| `coverage/README.md` | Updated to document `atlas.json` alongside `coverage.json` |
| `research/README.md` | Cleaned references to the removed `fee-schedules/` dir |
| `research/RUNBOOK-research.md` | §B is now an out-of-scope notice |
| `research/PIPELINE.md` | Removed Step type B (fee research) from the state machine |
| `research/COVERAGE_STRATEGY.md` | §10 rewritten from "fee-schedule data architecture (future work)" to "Fee data — out of scope" |
| `research/BACKLOG.md` | Reconciliation log scrubbed of specific amounts |
| `research/templates/office-synopsis.md` | §4 prescribes link-only fee policy |
| `research/specs/README.md` | Dropped "Source fee research" line from spec template; renamed `Verdict basis` → `Rating basis` |

---

## §8 Later 2026-05-18 — Africa wave + EPC sweep + playbook retirement

A second sub-session on 2026-05-18 (after the freshness audit above)
closed three threads.

### 8.1 Migration playbook retired (`d0a9ed9`)

Verified all 21 rows of `MIGRATION_PLAYBOOK.md` are done — every
register-side and substantive-law tool is on the §5.9 envelope with
provenance + lean/full + list-accept + Related-tools cross-refs. The
playbook itself was deleted (the per-shape templates and gotchas it
documented are absorbed into `CONNECTOR_STANDARDS.md` going forward).

Cleaned up 13 main-tree references that still cited "row N pending"
or pointed at the playbook as the canonical recipe; each repointed to
`CONNECTOR_STANDARDS.md` directly. CHANGELOG history + worktree copies
left intact.

### 8.2 Africa wave — all 6 surveyed offices red (`f0750af`)

Surveyed in 3 batches of 2 (to dodge the parallel-agent TPM stall
documented in [[feedback_parallel_agent_tpm_stall]]):

| Office | Verdict |
|---|---|
| **ZA/CIPC** | 🔴 red_blocked (IPS API "Coming Soon"; eServices T&Cs forbid derived works) |
| **EG/EGYPO + ITDA** | 🔴 red_no_api (**Law 163/2023 dissolves both into new EAIP** mid-transition) |
| **NG/FMITI + NCC** | 🔴 red_no_api (login-gated portals; NIPCOM bill not enacted) |
| **MA/OMPIC** | 🔴 red_no_api (despite being **the only African EPO Validation State**) |
| **ARIPO** | 🔴 red_no_api (HTML eService redirects to WIPO Publish; Journal PDFs) |
| **OAPI** | 🔴 red_no_api (**bare-IP HTTP-only register** at `195.24.202.12:9092`, no TLS) |

**6/6 red. Zero African IP offices appear in the WIPO IP API Catalog.**
The wave summary's strategic finding: don't build Africa-native
register connectors; the transitive layer is the answer.

**Context corrections discovered during research** (logged in
`research/BACKLOG.md` reconciliation log):
- **South Africa is NOT a Madrid Protocol member** (Trade Marks
  Amendment Bill stalled since 2003 approval — refuted prior assumption).
- **Nigeria is NOT a Madrid Protocol member** either.
- **Morocco's Hague Geneva Act accession was 2022-04-22** (not 1957 —
  that was 1934/1960-Act era).
- **ARIPO has 22 members and 5 protocols** (not 21/4) — Seychelles
  joined 2022; Mauritius Harare 2025-08-27; **Kampala Protocol** on
  voluntary copyright registration adopted 2024.
- **Egypt's Law 163/2023** dissolves EGYPO + ITDA into a new EAIP —
  transition in progress, no canonical web property yet.

Files: `research/waves/2026-05-18-africa-wave/{00-summary,za-cipc,
eg-egypto,ng-fmiti,ma-ompic,aripo,oapi}.md` (7 files, ~1,300 lines).

### 8.3 `green_transitive` rating + atlas expansion (`54420b9`, `704df9c`, `7d01e17`)

The Africa wave's transitive-coverage finding (ARIPO patents → EPO OPS
under country code `AP`; OAPI patents under `OA`) motivated a new
atlas convention: **transitive coverage = visible in the atlas.**

**New `green_transitive` rating** (🟢 "Green — Transitive") added to
`RATING_LABELS` in `scripts/build_coverage.py` for jurisdictions with
no native API but covered transitively through a regional or
higher-layer connector we already operate.

**66 new STATE.yaml entries** marked `green_transitive`:
- **Africa: 39** (22 ARIPO members + 17 OAPI members)
- **Europe: 28** EPC contracting states not previously surveyed (BE,
  BG, CY, CZ, DK, EE, GR, HR, HU, IE, LV, LT, LU, MT, PL, PT, RO, SK,
  SI for EU-19; AL, IS, LI, MC, ME, MK, NO, RS, SM for non-EU-9). Two
  flagged for follow-up research: **PL/UPRP** (only national EPC
  office in WIPO IP API Catalog) and **NO/Patentstyret** (historically
  publishing-forward).

**Sibling repo fix** (`patentclient-web@7d01e17`): the deployed
`atlas.js` hard-coded `RATING_VOCAB` map and `RATING_FAMILY(code) =>
code === "green" ? ...` only matched the literal `green` rating.
Without a fix, the 67 new entries would render as TBD-gray. Patched
both `atlas.js` and `landing-map.js` — RATING_VOCAB now includes
`green_transitive` and RATING_FAMILY uses `startsWith("green")`.

**Atlas summary delta:**

| Metric | Before | After |
|---|---|---|
| Total entities | 46 | 116 |
| `green_transitive` | 0 | 67 |
| Africa region | 1 | 43 |
| Europe region | 11 | 39 |

### 8.4 Norway YAML bug

Discovered during validation: unquoted `iso2: NO` in STATE.yaml
parses as YAML 1.1 boolean `False`. The "Norway problem" classic.
`NO/NIPO` was silently dropped from STATE entity processing until
quoted as `iso2: "NO"`. Audited the rest of the file — no other
YAML-reserved literal collisions.

### 8.5 Deployment

5 commits across 2 repos, all pushed:
- `patent-client-agents`: `d0a9ed9` (playbook retire) + `f0750af`
  (Africa wave) + `54420b9` (Africa atlas wiring) + `704df9c` (EPC
  sweep).
- `patentclient-web`: `7d01e17` (green_transitive vocab fix).

jsDelivr CDN purged after each `coverage/atlas.json` change per
`ATLAS_INTEGRATION.md` §8 deployment procedure (the original `§5`
queue assumed the priority-3 ARIPO/OAPI synopses would be done as
stubs; instead the wave produced full discovery research files
pointed at via `detail_survey`, and the atlas now surfaces the
ratings + basis text directly).

---

## §9 Updated atlas stats (as of 2026-05-18 evening)

```
total_entities: 116
by_rating:
  green:            11    (shipped connectors with live API access)
  green_transitive: 67    (covered via EPO OPS AP/OA or other regional)
  yellow_byok:      7     (per-user credential connectors planned)
  red_tos:          5     (ToS prohibits proxy)
  red_no_api:       19    (HTML-only, PDF-only, or bulk-only)
  red_blocked:      3     (access exists but is blocked)
  tbd:              4
by_region:
  multilateral:     6
  regional:         7
  americas:         6
  asia:             13
  europe:           39    (11 surveyed + 28 transitive)
  oceania:          2
  africa:           43    (4 surveyed nationals + 39 transitive; ARIPO/OAPI counted under regional)
```

This is the broadest, best-grounded atlas of programmatic-IP-data
access we've ever published — and the share of the world that's
*visible* as "covered" (green or green_transitive) jumped from
~24% (11/46) to ~67% (78/116) in one session, without any new
connector ship work.

---

## §10 Updated queue — what's next

Replaces the §5 queue (which was based on the morning's freshness
audit). Reordered after the later sub-session resolved most of §5's
priorities.

### Priority 1 — actual connector ship work

The next units of code-shipping value, in order of leverage:

| # | Item | Why | Effort |
|---|---|---|---|
| 1 | **Nordic SE/PRV + FI/PRH connectors** | Zero-auth REST/JSON across three hosts each; reverse-engineered from beta-UI `bundle.js`; CC0 / CC BY 4.0. SE covers 764k patents + structured TMs + designs. FI covers 393k patents + 282k TMs (back to 1891) + 33k designs. Same `nis-api-gateway` vendor infra → sibling-pattern build. | ~1-2 days each |
| 2 | **Multi-statute-corpus batch (BR/SG/IL/RU)** | Substantive-law sweep using the proven SQLite/FTS5 shape (`dpma_statutes` / `legifrance_ip` / `ipo_in_statutes` / `tw_trade_secrets`). Public-domain text, no ToS friction. Can batch-build. | ~1 day per jurisdiction |
| 3 | **Yellow_byok pick** | DE/DPMA (€200 wet contract), CH/IPI (datadelivery), ES/OEPM (5 free SOAP services), NZ/IPONZ (MBIE Azure APIM), or TH/DIP (21 APIs, paper contract). JPO/KIPO/INPI-France pattern. Env-gated off the hosted demo. | ~3-5 days each |

### Priority 2 — atlas/research follow-ups

| # | Item | Why | Effort |
|---|---|---|---|
| 1 | **PL/UPRP + NO/Patentstyret native API research** | Both flagged during the EPC sweep as having unusually digitally-mature postures; either could move from `green_transitive` to `green` if a native API exists at the right shape. | ~half day each |
| 2 | **Per-office synopses for the 4 surveyed African nationals** (ZA/EG/NG/MA) | Wave files exist; condense into `research/national/<iso2>-<office>.md` so `synopsis_url` populates in atlas drawer cards. | ~30 min each |
| 3 | **EAPO synopsis** | Still no synopsis for the Eurasian Patent Organization; the only major regional org without one in the atlas. Member states transitively covered via EPO OPS but the regional grant route is separate. | ~half day |

### Priority 3 — convention extensions

| # | Item | Why | Effort |
|---|---|---|---|
| 1 | **GCC member states as `green_transitive`** | Same pattern as ARIPO/OAPI: 6 Gulf states (AE, BH, KW, OM, QA, SA) covered transitively via GCC Patent (now legacy register only). But GCC patents stopped accepting new filings 2021-01-06; transitive value is for the legacy register only. | ~30 min |
| 2 | **EAPO member states** | RU + 7 ex-Soviet states; EAPO is the Eurasian regional. Same `green_transitive` shape, but politically sensitive given sanctions. Defer until EAPO synopsis lands. | ~30 min |

### Watch items (recheck quarterly)

- **SA Madrid Protocol accession** — TMs Amendment Bill stalled since 2003 approval; quarterly check on Parliament progress.
- **NG NIPCOM bill** — not yet enacted; NIPPS approved 2025-11-06 but only proposes prospective digitization.
- **EG EAIP consolidation** — transition deadline was 2024-08-05 +6 months; check for a canonical web property + any new API surface.
- **CIPC IPS API GA** — marked "Coming Soon" on developer.cipc.co.za APIVerse Hub.
- **WIPO Brand DB partner API** — undocumented `public-api.branddb.wipo.int` returns "Missing Authentication Token"; suggests future partner program.
- **UKIPO One IPO Patents Service** — launched 2026-03-31 without a search API; recheck for timeline announcement.
- **CIPO NGP REST API** — ISED API Catalogue may get new entries; mid-rollout.

### Out of scope (don't pursue)

- Africa register-side native connectors — wave verdict is settled.
- EU register-side native connectors for jurisdictions without their own API — `green_transitive` is the right rating; pursuing native connectors duplicates EPO OPS coverage.
- WIPO Global Brand DB / Global Design DB direct — ToS and CAPTCHA-walled.
- DPMAconnectPlus on the hosted demo — paid contract clause restricts proxy redistribution.
