names/CLAUDE.md

names — Business Name Finder

Free business-name generator with live domain availability, at names.poweredbyotm.com. A first-party Powered by OTM app.

• Stack: Next.js 15 (App Router, output: "standalone"), React 18, no DB, no auth, public. Generation runs client-side; availability is a server route (browsers can't do DNS, and RDAP servers send no CORS headers).
• Repo: tonym/names on git.poweredbyotm.com.
• Deploy: platform MCP — build_app("names") then deploy_app("names"). NOT docker-compose-from-this-repo. Prod deploys need Tony's explicit OK.

README.md explains the mechanisms in full. This file is the house rules.

Deploy

Registered in platform/apps/otm-admin/lib/first-party-apps.ts as publicAccess: true, needsDb: false, needsAuthSecret: false, needsSuggestions: true, uploads: "/app/public/uploads".

Adding this app to the registry required an otm-admin release (0.113.0) — and because the auto-deploy webhook is gated on green CI, names does not appear in /apps until platform CI passes and otm-admin redeploys (~2.5 min). build_app before that point fails on an unknown app id.

build_app times out at the MCP layer and keeps building. That's normal, not a failure. Poll for the image instead of retrying the call:

ssh debian@51.81.80.250 'docker images platform-names --format "{{.Repository}} {{.CreatedSince}}"'

Verify a deploy against the LIVE site, never the deploy log:

curl -s https://names.poweredbyotm.com/api/health
curl -s -X POST https://names.poweredbyotm.com/api/availability \
  -H 'content-type: application/json' \
  -d '{"domains":["google.com","zzq7xk4m.io"]}'   # expect taken + unverified-available

Availability — the trap

Never route lookups through rdap.org. Its redirector returns a bare 404 both for "this domain is unregistered" and for "I have no RDAP server for this TLD" — the two are indistinguishable from the status code. Routing through it would report every .io as available. We resolve the TLD ourselves from IANA's bootstrap (data.iana.org/rdap/dns.json, cached 24h) and query the authoritative server directly, so a 404 can only mean unregistered.

The TLDs with no RDAP at all (.io .co .me .sh .gg .us .de) fall back to a DNS NS lookup. That path can only ever return unverified-available, shown amber as probably free — a registered-but-undelegated domain looks identical. Do not "upgrade" it to a green check.

We're an anonymous client against other people's public endpoints. Keep the manners: 60 domains/request, 8-wide concurrency, per-IP token bucket, 10-minute result cache.

Generation — three guards that must not be relaxed

src/lib/generate.ts is pure and deterministic. The strategies are deliberately cheap and dumb; quality lives in scoreName — tune the scorer before adding vocabulary. Each of these exists because of specific bad output, and removing it brings that output straight back:

• expandKeywords matches category hints by prefix, never substring. Plain containment let repair match the ai category (rep-ai-r) and dragged neural-network words into an auto-shop brief.
• syncopate only drops the schwa from a final -er (flicker → flickr). The original "drop the last vowel" gave crema → crem, kettle → kettl, security → securit.
• isTruncation rejects any candidate that is a strict prefix of a word the generator knows. This is what keeps stumps out of the results.

diversify() caps each strategy at ~28% of the list. Without it the top 20 came back as eighteen coinages — raw score ranking clumps badly.

Shared OTM widgets need Tailwind

The bottom-right feedback chat-pop is SuggestionLightbulb from @otm/account-panel, styled with Tailwind utilities. This app's own UI is plain CSS, and for a while it had no Tailwind at all — so the widget rendered as a bare unstyled button (issue #2). Tailwind is configured with preflight: false (it must not reset the handwritten CSS) and its content includes node_modules/@otm/account-panel/src. Element-level rules in globals.css are scoped to .wrap, and the widget mounts outside .wrap, so neither side can restyle the other. Keep it that way when adding global CSS.

Wishlist is browser-only

src/lib/wishlist.ts — localStorage key names.wishlist, capped at 60. It snapshots the last-seen status per domain; the Finder keeps snapshots fresh from live lookups and Re-check re-queries through the normal availability route. No server state, on purpose.

Keys stay in the browser

Optional AI names use the visitor's own Anthropic/Gemini key from localStorage (names.aiKey), called browser-direct — same pattern as rpo's Google Vision key, for the same reason: the platform has no per-app env tool, and a free public tool must not hold a metered credential. The anthropic-dangerous-direct-browser-access header is correct here and would be wrong in a product that owns the key.

Registrar links

src/lib/registrars.ts. Links are plain today (every affiliateCode is ""). Fill one in and HAS_AFFILIATE_LINKS flips the footer disclosure on automatically. Keep the code and the disclosure in that one file — a disclosure that can drift out of sync with whether links actually pay is worse than none.