@fredcallagan/arn-spark 5.1.0

package/plugins/arn-spark/skills/arn-spark-naming/references/naming-methodology.md

@@ -0,0 +1,237 @@
+# Brand Naming Methodology
+
+## The Four Steps
+
+### Step 1: Strategic Foundation (Brand DNA)
+
+**Goal:** Define the naming "North Star" — the strategic constraints that shape every name candidate.
+
+**Inputs:** Product context (vision, value proposition, target audience, product pillars, competitive landscape), target market/country.
+
+**Process:**
+1. Analyze the target audience's vocabulary, communication style, and expectations
+2. Distill the value proposition into a single differentiating statement
+3. Profile the brand personality using archetypes (e.g., "The Reliable Expert," "The Rebellious Newcomer," "The Friendly Guide")
+4. Research competitor name landscape — identify naming patterns in the space (are most names descriptive? evocative? invented?)
+5. Recommend naming categories based on personality, audience, and competitive whitespace
+6. Collect user seeds: existing ideas, loved words, hated words
+
+**Output:** Creative brief (naming-brief.md with Context and Brand DNA sections)
+
+### Step 2: Creative Sprint (The Big List)
+
+**Goal:** Maximum volume of candidates. Quality filtering comes later.
+
+**Inputs:** Creative brief, selected naming categories, user seeds.
+
+**Process:**
+- Round 1 (Seed harvest): Process user's existing ideas and preferences as starting points
+- Round 2 (Category sprints): Generate 50-80 candidates per selected category using generation techniques
+- Round 3 (Mashup round): Cross-pollinate fragments — combine prefixes from one candidate with suffixes from another, blend concepts across categories
+- Round 4 (User checkpoint): Present all candidates organized by category for user starring and direction-killing
+
+**Target:** 200+ candidates across all rounds.
+
+**Output:** Updated naming-brief.md with Creative Sprint Results section.
+
+### Step 3: Qualitative Filter (Six Senses)
+
+**Goal:** Reduce the big list to a shortlist of scored, evaluated candidates.
+
+**Inputs:** Full candidate list, user-starred favorites, dead directions.
+
+**Process:**
+- Pass 1: Quick filter from 200+ to 30-40 (remove obvious duds, unpronounceable names, too-similar pairs)
+- Pass 2: Score each of the 30-40 on the Six Senses Framework (see below). Present scored table.
+- User selects 5-8 finalists for due diligence.
+
+**Output:** Updated naming-brief.md with Qualitative Filter Results section.
+
+### Step 4: Cold Shower (Due Diligence)
+
+**Goal:** Validate finalists against real-world constraints before committing.
+
+**Inputs:** 5-8 finalist names, target market/country, industry.
+
+**Process:**
+- Domain availability check (WHOIS)
+- Trademark screening (websearch + database URLs)
+- Linguistic screening (multilingual connotation check)
+- Social media handle check
+
+**Output:** Updated naming-brief.md with Due Diligence and Final Decision sections. Naming report written to reports directory.
+
+---
+
+## The Six Senses Framework
+
+Six lenses for evaluating brand name quality. Each scored 1-5.
+
+### 1. Appearance (Visual Punch)
+
+How the name looks on screen, in print, on an app icon.
+
+| Score | Criteria |
+|-------|----------|
+| 1 | Visually cluttered, awkward letter combinations, too long (>10 characters) |
+| 2 | Passable but forgettable visually, some awkward letter pairs |
+| 3 | Clean and readable, reasonable length (7-8 characters) |
+| 4 | Visually balanced, good letter variety, compact (5-6 characters) |
+| 5 | Striking on sight, elegant letter shapes, perfect length (4-6 characters), logo-friendly |
+
+**Key questions:** Does it look good in a URL bar? On a mobile app icon? In a logo? How many characters?
+
+### 2. Sound (Euphony)
+
+How the name sounds when spoken aloud.
+
+| Score | Criteria |
+|-------|----------|
+| 1 | Tongue-twister, harsh consonant clusters, hard to pronounce |
+| 2 | Pronounceable but unpleasant rhythm, ambiguous pronunciation |
+| 3 | Sounds fine, clear pronunciation, no stumbling |
+| 4 | Pleasant to say, good rhythm, natural stress pattern |
+| 5 | Euphonious (delightful to say), musical quality, passes the Phone Test without spelling |
+
+**Phone Test:** Say the name to someone over the phone. Can they write it correctly without asking for spelling? If yes, it passes.
+
+### 3. Meaning (Associations)
+
+What the name triggers in the listener's mind.
+
+| Score | Criteria |
+|-------|----------|
+| 1 | Wrong associations, confusing, or generic to the point of meaninglessness |
+| 2 | Weak or irrelevant associations, requires explanation |
+| 3 | Neutral — no negative associations, some positive potential |
+| 4 | Evokes the right mental image, hints at the product's purpose or personality |
+| 5 | Rich associations that reinforce the brand story (like Tesla = electricity + innovation + history) |
+
+**Key questions:** What does someone picture when they hear this name for the first time? Does it align with the product's brand personality?
+
+### 4. Memorability (Stickiness)
+
+How well the name lodges in memory after a single exposure.
+
+| Score | Criteria |
+|-------|----------|
+| 1 | Instantly forgettable, blends with similar-sounding names |
+| 2 | Might remember it with effort, no hooks |
+| 3 | Reasonably memorable, standard pattern |
+| 4 | Sticky — uses alliteration, rhyme, or surprise to anchor in memory |
+| 5 | Unforgettable after one hearing (like Coca-Cola's alliterative rhythm or Uber's brevity) |
+
+**The Morning-After Test:** If someone hears the name once at dinner, can they recall it the next morning?
+
+### 5. Function (Real-World Utility)
+
+How the name performs in practical, everyday contexts.
+
+| Score | Criteria |
+|-------|----------|
+| 1 | Hard to type, impossible to verbalize as an action, doesn't fit on a small icon |
+| 2 | Awkward to type or spell, clumsy in conversation |
+| 3 | Works fine in all practical contexts, no friction |
+| 4 | Easy to type on mobile, natural as a verb ("let me [name] that"), clean as a handle |
+| 5 | Frictionless everywhere — types fast, verbs naturally, looks clean as @handle, fits a favicon |
+
+**Key questions:** Can it be used as a verb? Is it easy to type on a mobile keyboard? Does `@name` work as a social handle? Does it fit on a 16x16 favicon?
+
+### 6. Scalability (Growth Headroom)
+
+Whether the name constrains or enables future product evolution.
+
+| Score | Criteria |
+|-------|----------|
+| 1 | Locks the product into a specific feature, market, or technology that may change |
+| 2 | Somewhat limiting — works for v1 but would feel awkward if the product expanded |
+| 3 | Neutral — doesn't constrain but doesn't actively enable expansion |
+| 4 | Flexible enough to cover adjacent markets or features without rebranding |
+| 5 | Name is a platform — could encompass an entire ecosystem (like Amazon expanding from books to everything) |
+
+**Key questions:** If the product adds a major new feature, does the name still work? If it enters a new market segment? If it becomes a platform?
+
+---
+
+## Naming Categories
+
+### Descriptive
+Names that literally describe what the product does.
+
+**Examples:** PayPal, General Motors, YouTube, Dropbox, Salesforce
+
+**Strengths:** Instant clarity, low marketing spend to explain, good for B2B
+**Weaknesses:** Can feel boring, hard to trademark (common words), limits scalability
+**Generation techniques:** Core function words, benefit statements, action + object combinations
+**Best for:** Products where clarity matters more than mystique; enterprise/B2B; utility tools
+
+### Evocative
+Names that suggest a feeling, atmosphere, or metaphor rather than a literal description.
+
+**Examples:** Patagonia, Amazon, Nike, Slack, Notion, Asana
+
+**Strengths:** Emotional resonance, strong brand storytelling, highly memorable, good scalability
+**Weaknesses:** Requires more marketing to establish the connection, meaning may be obscure initially
+**Generation techniques:** Metaphors, nature words, mythological references, emotional states, journey/destination words, abstract concepts that map to the product's personality
+**Best for:** Consumer products, lifestyle brands, products with a strong personality or mission
+
+### Invented / Abstract
+Completely new words with no prior dictionary meaning.
+
+**Examples:** Kodak, Google, Xerox, Spotify, Skype, Hulu
+
+**Strengths:** Unique, highly trademarkable, no prior associations to compete with, strong domain availability
+**Weaknesses:** Requires high marketing budget to establish meaning, no inherent semantic cues
+**Generation techniques:** Phoneme combination (choosing sounds that feel right), truncation + recombination, vowel/consonant pattern play, syllable blending from relevant roots, portmanteau of related concepts
+**Best for:** Products aiming for category ownership, well-funded brands, products where uniqueness trumps immediate clarity
+
+### Lexical
+Names that use wordplay, puns, alliteration, rhyme, or creative spelling.
+
+**Examples:** Dunkin' Donuts, Krispy Kreme, Pinterest (pin + interest), Groupon (group + coupon), Netflix (net + flicks), Flickr
+
+**Strengths:** Fun and memorable, built-in hooks for memory, often feel approachable and playful
+**Weaknesses:** Can feel unprofessional for serious products, puns may not translate across languages
+**Generation techniques:** Alliterative pairs, rhyming combinations, portmanteau (blending two words), creative misspelling (dropping vowels, swapping letters), puns on industry terms
+**Best for:** Consumer products, social/community platforms, products targeting younger demographics, anything where playfulness matches the brand personality
+
+---
+
+## Generation Techniques (Detail)
+
+### Mind Mapping
+Start with the product's core concept at the center. Branch into:
+- Synonyms and near-synonyms
+- Metaphors and analogies
+- Emotional associations
+- Sensory descriptions
+- Related fields and domains
+- Actions and outcomes
+
+Each branch can spawn sub-branches. Aim for 3-4 levels deep.
+
+### Thesaurus Mining
+For each key concept word:
+1. Look up synonyms in English
+2. Look up Latin and Greek roots
+3. Explore words in related semantic fields (not just synonyms)
+4. Check archaic or poetic forms of the word
+5. Look for words in other languages that capture the concept
+
+### Word Hacking
+Systematic transformation techniques:
+- **Portmanteau:** Blend two words (Pinterest = pin + interest)
+- **Truncation:** Shorten a word (Cisco from San Francisco)
+- **Vowel removal:** Drop vowels (Flickr, Tumblr)
+- **Suffix addition:** Add tech/brand suffixes (-ify, -ly, -io, -ia, -able, -ware, -hub)
+- **Prefix addition:** Add aspirational prefixes (super-, ultra-, pro-, neo-, meta-)
+- **Letter swap:** Change one letter for a different feel
+- **Respelling:** Phonetic spelling of an existing word (Lyft)
+
+### Etymology Exploration
+Dig into word origins:
+- Latin roots (often carry gravitas and universality)
+- Greek roots (often associated with science, knowledge)
+- Norse/Germanic roots (strength, reliability)
+- Japanese/Sanskrit (harmony, mindfulness)
+- Choose roots that map to the product's personality and values

package/plugins/arn-spark/skills/arn-spark-naming/references/naming-report-template.md

@@ -0,0 +1,122 @@
+# Naming Report
+
+> **Instructions:** This report is the final deliverable from the naming process. Every section MUST appear. Replace all bracketed placeholders. Write to `<reports-dir>/naming-report.md`.
+
+**Product:** [Product name or working title]
+**Date:** [ISO 8601]
+**Methodology:** 4-Step Brand Naming (Strategic Foundation → Creative Sprint → Qualitative Filter → Due Diligence)
+**Target market:** [Country/region]
+**Naming categories explored:** [Category list]
+
+---
+
+## Executive Summary
+
+[3-5 sentences: how many candidates were generated, what categories were explored, how many survived each filter stage, the final recommendation and key rationale. This should be readable as a standalone summary.]
+
+---
+
+## Creative Brief Summary
+
+- **Brand personality:** [1-sentence personality profile]
+- **Key differentiator:** [The value proposition that shaped naming direction]
+- **Competitor naming pattern:** [1-sentence summary of how competitors name themselves]
+- **Categories selected:** [List with brief rationale]
+- **User direction:** [Key preferences or constraints from the user]
+
+---
+
+## Generation Statistics
+
+| Category | Round 1 (Seeds) | Round 2 (Sprint) | Round 3 (Mashup) | Total |
+|----------|----------------|-------------------|-------------------|-------|
+| [Category 1] | [N] | [N] | [N] | [N] |
+| [Category 2] | [N] | [N] | [N] | [N] |
+| **Total** | **[N]** | **[N]** | **[N]** | **[N]** |
+
+**Pass 1 filter:** [N] candidates → [N] shortlisted (top [X]%)
+
+---
+
+## Qualitative Filter: Six Senses Scored Table
+
+Finalists only. Scored 1-5 per sense, total 6-30.
+
+| Rank | Name | Appear. | Sound | Meaning | Memory | Function | Scale | Total |
+|------|------|---------|-------|---------|--------|----------|-------|-------|
+| 1 | [name] | [1-5] | [1-5] | [1-5] | [1-5] | [1-5] | [1-5] | [/30] |
+| 2 | [name] | [1-5] | [1-5] | [1-5] | [1-5] | [1-5] | [1-5] | [/30] |
+| ... | | | | | | | | |
+
+---
+
+## Due Diligence Matrix
+
+### Domain Availability
+
+| Name | .com | .io | .co | .dev | .app | .ai |
+|------|------|-----|-----|------|------|-----|
+| [name] | [Available ✓ / Taken ✗ / Unknown ?] | | | | | |
+
+**Method:** [RDAP (primary) / WHOIS port-43 (fallback) / System whois / Manual check]
+**Date checked:** [ISO 8601]
+**Notes:** [Per-domain method used (from script `method` field), any partial results due to rate limiting, RDAP-only TLDs]
+
+### Trademark Screening
+
+| Name | Automated Search | Risk Level | Notes |
+|------|-----------------|-----------|-------|
+| [name] | [Summary] | [Clear / Caution / Conflict] | [Details] |
+
+**Databases recommended for manual check:** [URLs based on target market]
+
+### Linguistic Screening
+
+| Name | Languages Checked | Issues Found |
+|------|------------------|-------------|
+| [name] | [Language list] | [None / Description] |
+
+### Social Media Handles
+
+| Name | X / Twitter | Instagram | GitHub |
+|------|-----------|-----------|--------|
+| [name] | [✓ / ✗ / ?] | [✓ / ✗ / ?] | [✓ / ✗ / ?] |
+
+---
+
+## Final Recommendation
+
+### Chosen Name: **[Name]**
+
+**Rationale:** [2-3 sentences — reference Six Senses scores, due diligence results, brand DNA alignment, and competitive differentiation.]
+
+**Six Senses total:** [N]/30
+**Domain status:** [Summary]
+**Trademark status:** [Summary]
+**Linguistic status:** [Clear / Flagged items]
+
+### Runner-Ups (Ordered)
+
+1. **[Name]** ([N]/30) — [Brief rationale for runner-up position]
+2. **[Name]** ([N]/30) — [Brief rationale]
+3. **[Name]** ([N]/30) — [Brief rationale]
+
+---
+
+## All Candidates
+
+Full candidate list organized by category, preserved for future reference or second-pass evaluation.
+
+### [Category 1]
+
+[Numbered list]
+
+### [Category 2]
+
+[Numbered list]
+
+---
+
+## Disclaimer
+
+This report contains preliminary screening results for informational purposes. Domain availability and trademark status are point-in-time snapshots and may change. **Consult a qualified trademark attorney before committing to a brand name for commercial use.** This report does not constitute legal advice.

package/plugins/arn-spark/skills/arn-spark-naming/references/trademark-databases.md

@@ -0,0 +1,88 @@
+# Trademark Databases by Country/Region
+
+## Database Directory
+
+### United States — USPTO TESS
+
+- **URL:** https://tmsearch.uspto.gov/
+- **Coverage:** US federal trademark registrations and pending applications
+- **Search type:** Word mark search (exact and fuzzy)
+- **Instructions:** Enter the brand name in the "Search Term" field. Select "Word Mark" as the search type. Review results for exact matches and phonetic equivalents in the same Nice Classification class.
+- **Nice Classification:** Check the class(es) relevant to the product's industry. Common tech classes: 9 (software/hardware), 35 (advertising/business services), 38 (telecommunications), 42 (SaaS/technology services).
+- **Note:** TESS searches only US trademarks. A clear US result does not guarantee clearance in other jurisdictions.
+
+### European Union — EUIPO eSearch
+
+- **URL:** https://euipo.europa.eu/eSearch/
+- **Coverage:** EU-wide trademark registrations (EUTMs) covering all 27 member states
+- **Search type:** Trademark search with text, image, and classification filters
+- **Instructions:** Select "Trade marks" tab. Enter the brand name. Filter by Nice Classification. Review results for exact and similar marks.
+- **Note:** An EUTM registration provides protection across all EU member states simultaneously.
+
+### United Kingdom — IPO
+
+- **URL:** https://www.gov.uk/search-for-trademark
+- **Coverage:** UK trademark registrations (post-Brexit, separate from EU)
+- **Instructions:** Enter the brand name. Review registered and pending marks. Check Nice Classification alignment.
+- **Note:** Since Brexit, UK and EU trademarks are separate systems. Check both if targeting both markets.
+
+### Global — WIPO Global Brand Database
+
+- **URL:** https://branddb.wipo.int/
+- **Coverage:** 70+ jurisdictions, Madrid System international registrations
+- **Search type:** Text, image, and phonetic search
+- **Instructions:** Enter the brand name in the search field. Use "Text" search for exact/similar word marks. Filter by designated countries and Nice Classification.
+- **Important:** WIPO's terms of use prohibit automated querying. Use only for manual verification.
+- **Note:** The Global Brand Database aggregates data from many national offices but may not be complete for all jurisdictions. Always verify critical results with the national office.
+
+### Australia — IP Australia
+
+- **URL:** https://search.ipaustralia.gov.au/trademarks/search/quick
+- **Coverage:** Australian trademark registrations and applications
+- **Instructions:** Enter the brand name in Quick Search. Review results for registered and pending marks in relevant classes.
+
+### Canada — CIPO
+
+- **URL:** https://ised-isde.canada.ca/cipo/trademark-search/srch
+- **Coverage:** Canadian trademark registrations and applications
+- **Instructions:** Enter the brand name. Search by "Trade-mark" type. Review results for similar marks.
+
+---
+
+## Country-to-Database Mapping
+
+| Target Market | Primary Database(s) | Also Check |
+|--------------|--------------------|-----------:|
+| United States | USPTO TESS | WIPO Global Brand Database |
+| European Union | EUIPO eSearch | WIPO Global Brand Database |
+| United Kingdom | IPO | EUIPO (if also targeting EU), WIPO |
+| Global / Multiple | WIPO Global Brand Database | USPTO + EUIPO + IPO (for the three largest markets) |
+| Australia | IP Australia | WIPO |
+| Canada | CIPO | WIPO |
+| Other | WIPO Global Brand Database | Country-specific office (search for "[country] trademark registry") |
+
+---
+
+## Nice Classification — Common Tech Classes
+
+| Class | Description | Examples |
+|-------|------------|---------|
+| 9 | Computer software, hardware, mobile apps, downloadable content | SaaS products, mobile apps, desktop software |
+| 35 | Advertising, business management, online retail services | Marketing platforms, e-commerce, analytics tools |
+| 38 | Telecommunications, messaging, data transmission | Chat apps, video conferencing, communication tools |
+| 42 | Scientific/technological services, SaaS, cloud computing, software development | Developer tools, cloud platforms, API services |
+| 41 | Education, training, entertainment, publishing | EdTech, content platforms, gaming |
+
+**Tip:** Most software products should check at least classes 9 and 42. If the product includes a marketplace or advertising component, also check class 35. If it involves communication, check class 38.
+
+---
+
+## Search Best Practices
+
+1. **Search for exact match AND phonetic equivalents.** "Lyft" and "Lift" are phonetically identical and could conflict.
+2. **Check multiple Nice Classification classes.** A product may span several classes.
+3. **Search for the name alone AND with common modifiers.** Check "Spark" and "SparkApp" and "Spark.io" separately.
+4. **Look at both registered marks AND pending applications.** A pending application may block registration.
+5. **Check word marks, not just logos.** A word mark registration covers the word regardless of styling.
+6. **Remember that trademark rights are territorial.** A name clear in the US may be registered in the EU.
+7. **Consider common-law (unregistered) trademarks.** Not all trademarks are registered. A websearch for the name + industry can surface unregistered usage.

package/plugins/arn-spark/skills/arn-spark-naming/references/whois-server-map.md

@@ -0,0 +1,164 @@
+# WHOIS & RDAP Server Map
+
+The scripts use **RDAP as the primary lookup method** with port-43 WHOIS as a fallback. RDAP servers are discovered dynamically via the IANA bootstrap file (`https://data.iana.org/rdap/dns.json`) which covers 1,198+ TLDs. The WHOIS server map below is used only as a fallback when RDAP is unavailable for a TLD.
+
+Since January 2025 (ICANN sunset), 374+ gTLDs have dropped port-43 WHOIS entirely. TLDs like `.dev`, `.app`, and `.land` are RDAP-only.
+
+## TLD to WHOIS Server (Fallback)
+
+| TLD | WHOIS Server | Port | Notes |
+|-----|-------------|------|-------|
+| `.com` | `whois.verisign-grs.com` | 43 | Also handles `.net` |
+| `.net` | `whois.verisign-grs.com` | 43 | Same server as `.com` |
+| `.org` | `whois.pir.org` | 43 | Public Interest Registry |
+| `.io` | `whois.nic.io` | 43 | Popular for tech products |
+| `.co` | `whois.registry.co` | 43 | Colombia ccTLD, used as generic. Note: `whois.nic.co` is NXDOMAIN — use `whois.registry.co` |
+| `.dev` | — | — | **RDAP-only** (`pubapi.registry.google/rdap/`). No port-43 WHOIS server exists |
+| `.app` | — | — | **RDAP-only** (`pubapi.registry.google/rdap/`). No port-43 WHOIS server exists |
+| `.ai` | `whois.nic.ai` | 43 | Anguilla ccTLD, popular for AI products |
+| `.me` | `whois.nic.me` | 43 | Montenegro ccTLD, used for personal brands |
+| `.xyz` | `whois.nic.xyz` | 43 | Generic TLD |
+| `.tech` | `whois.nic.tech` | 43 | Tech-focused TLD |
+| `.so` | `whois.nic.so` | 43 | Somalia ccTLD |
+| `.sh` | `whois.nic.sh` | 43 | Saint Helena ccTLD |
+| `.to` | `whois.tonic.to` | 43 | Tonga ccTLD |
+| `.gg` | `whois.gg` | 43 | Guernsey ccTLD |
+| `.ly` | `whois.nic.ly` | 43 | Libya ccTLD, used for -ly names |
+| `.is` | `whois.isnic.is` | 43 | Iceland ccTLD |
+| `.fm` | `whois.nic.fm` | 43 | Micronesia ccTLD |
+| `.tv` | `whois.nic.tv` | 43 | Tuvalu ccTLD, media use |
+| `.cc` | `ccwhois.verisign-grs.com` | 43 | Cocos Islands ccTLD |
+
+### Country-Code TLDs (Single-Part)
+
+| TLD | WHOIS Server | Port | Notes |
+|-----|-------------|------|-------|
+| `.de` | `whois.denic.de` | 43 | Germany |
+| `.fr` | `whois.nic.fr` | 43 | France |
+| `.it` | `whois.nic.it` | 43 | Italy |
+| `.es` | `whois.nic.es` | 43 | Spain |
+| `.nl` | `whois.sidn.nl` | 43 | Netherlands |
+| `.eu` | `whois.eu` | 43 | European Union |
+| `.us` | `whois.nic.us` | 43 | United States |
+| `.ca` | `whois.cira.ca` | 43 | Canada |
+| `.br` | `whois.registro.br` | 43 | Brazil |
+| `.jp` | `whois.jprs.jp` | 43 | Japan |
+| `.in` | `whois.registry.in` | 43 | India |
+| `.au` | `whois.auda.org.au` | 43 | Australia |
+| `.pt` | `whois.dns.pt` | 43 | Portugal |
+| `.pl` | `whois.dns.pl` | 43 | Poland |
+| `.se` | `whois.iis.se` | 43 | Sweden |
+| `.ch` | `whois.nic.ch` | 43 | Switzerland |
+| `.at` | `whois.nic.at` | 43 | Austria |
+| `.be` | `whois.dns.be` | 43 | Belgium |
+| `.mx` | `whois.mx` | 43 | Mexico |
+| `.ar` | `whois.nic.ar` | 43 | Argentina |
+| `.cl` | `whois.nic.cl` | 43 | Chile |
+| `.kr` | `whois.kr` | 43 | South Korea |
+
+### Compound Country-Code TLDs
+
+These have two-part TLD structures. The scripts check compound TLDs before single-part to ensure correct server routing (e.g., `example.com.br` → `com.br`, not `br`).
+
+| TLD | WHOIS Server | Port | Notes |
+|-----|-------------|------|-------|
+| `.co.uk` | `whois.nic.uk` | 43 | United Kingdom |
+| `.org.uk` | `whois.nic.uk` | 43 | United Kingdom |
+| `.com.br` | `whois.registro.br` | 43 | Brazil |
+| `.com.au` | `whois.auda.org.au` | 43 | Australia |
+| `.co.jp` | `whois.jprs.jp` | 43 | Japan |
+| `.co.in` | `whois.registry.in` | 43 | India |
+| `.com.mx` | `whois.mx` | 43 | Mexico |
+| `.com.ar` | `whois.nic.ar` | 43 | Argentina |
+| `.co.kr` | `whois.kr` | 43 | South Korea |
+| `.com.pt` | `whois.dns.pt` | 43 | Portugal |
+
+## Target Market to Suggested TLDs
+
+| Target Market | TLDs to Check |
+|--------------|---------------|
+| United States | `.com`, `.io`, `.co`, `.dev`, `.app`, `.ai`, `.us` |
+| European Union | `.com`, `.io`, `.eu`, `.de`, `.fr`, `.it`, `.es`, `.nl` |
+| United Kingdom | `.com`, `.io`, `.co.uk`, `.org.uk` |
+| Brazil | `.com`, `.com.br` |
+| Australia | `.com`, `.com.au`, `.io` |
+| Canada | `.com`, `.ca`, `.io` |
+| Japan | `.com`, `.jp`, `.co.jp` |
+| India | `.com`, `.in`, `.co.in` |
+| Global / Multiple | `.com`, `.io`, `.co`, `.dev`, `.app`, `.ai` + relevant local TLDs |
+
+## RDAP (Primary Method)
+
+RDAP (Registration Data Access Protocol) is the IETF standard replacement for port-43 WHOIS. It uses HTTPS and returns structured JSON:
+- **HTTP 200** = domain is registered (taken). Response includes registrar, status, dates.
+- **HTTP 404** = domain not found in registry (available).
+- **HTTP 429** = rate limited (circuit breaker trigger).
+
+The IANA bootstrap file at `https://data.iana.org/rdap/dns.json` maps 1,198+ TLDs to their RDAP endpoints. Scripts load this once at startup — no hardcoded RDAP map needed.
+
+## Fallback for Unknown TLDs
+
+For RDAP: the IANA bootstrap covers most TLDs. If a TLD is not in the bootstrap, the scripts fall through to port-43 WHOIS.
+
+For port-43 WHOIS: query `whois.iana.org` with the TLD (e.g., send `example\r\n`). The response includes the authoritative WHOIS server under the "whois:" field. Some TLDs return an empty "whois:" field — these are RDAP-only.
+
+## Availability Indicator Patterns
+
+### Patterns Indicating AVAILABLE (domain not registered)
+
+```
+No match for
+NOT FOUND
+No entries found
+No Data Found
+Domain not found
+No information available
+Status: AVAILABLE
+The queried object does not exist
+No Object Found
+DOMAIN NOT FOUND
+is available for
+```
+
+### Patterns Indicating TAKEN (domain registered)
+
+```
+Domain Name:
+Registrar:
+Creation Date:
+Registry Expiry Date:
+Updated Date:
+Name Server:
+Registrant:
+Status: ok
+Status: clientTransferProhibited
+```
+
+### Ambiguous / Rate Limit Patterns
+
+```
+quota exceeded
+rate limit
+too many requests
+Please try again later
+Your request has been throttled
+Connection limit reached
+Access denied
+```
+
+When an ambiguous or rate limit response is received, the domain status should be reported as `null` (unknown) and the circuit breaker should activate.
+
+## Known Rate Limit Policies
+
+These are approximate and should be verified via websearch before each run:
+
+| Server | Known Limit | Safe Delay |
+|--------|-----------|-----------|
+| `whois.verisign-grs.com` (.com/.net) | ~1 query/second per IP | 2s |
+| `whois.pir.org` (.org) | Not published; conservative recommended | 3s |
+| `whois.nic.io` (.io) | Aggressive limiting reported | 3s |
+| `whois.nic.google` (.dev/.app) | Not published | 2s |
+| `whois.nic.ai` (.ai) | Known for slow responses | 3s |
+| General recommendation | 1-2 queries/second typical | 2-3s |
+
+**Important:** Rate limits change. Before running batch queries, use websearch to check current policies for the target TLD's WHOIS server. The delay_seconds parameter should be set to the most conservative limit discovered across all target TLDs.