{ "name": "The Doozer Brain (public edition)", "description": "Doozer's complete working knowledge in Open Knowledge Format. Generated live; never a snapshot.", "format": "OKF v0.2", "owner": "BerrySmart", "generated": "2026-09-13T21:13:55+00:00", "node_count": 93, "held_back": 13, "note": "Omissions are operational security only (infrastructure failure modes, internal endpoint auth, claim-code mechanics). No strategy, economics, or product thinking has been removed.", "markdown_url": "https://doozer.work/brain", "nodes": [ { "id": "index", "title": "The Doozer Brain", "type": "Index", "group": "root", "description": "Doozer's complete knowledge in Open Knowledge Format — the idea, direction, systems, processes, value, and vocabulary behind the entire platform.", "tags": [ "okf", "brain", "index" ], "path": "index.md", "links": [ "okf-adoption", "AGENTS", "model-handoff", "working-with-jon", "the-mission", "the-doozer-story", "architecture", "the-network", "the-value-model", "the-flywheel", "two-tier-model", "the-observed-world", "index", "category-aware-call-intent", "hostile-css-environment", "skeleton-first-index-later", "self-healing-email-backfill", "price-the-pull-before-you-pull", "fix-the-source-not-the-symptom", "inline-the-bytes", "cross-root-identity", "derive-dont-store-the-active-domain", "adaptive-logo-shape", "the-distraction-problem", "decision-vs-delivery", "nearbymenow", "network-growth", "clouds", "directory-framework", "muse-system", "design-standards", "brand-system", "content-generation", "best-ai-for-the-job", "fact-guard", "location-data-enrichment", "weather-widget", "shared-business-card", "section-framework", "lead-capture", "leadbuilder", "billing", "money-clouds", "prospector", "marketing", "shortlinks", "growth-engine", "ai-postcards", "thanksio", "promo-and-offers", "doozer-prospects", "machi", "event-feeds", "indexnow", "ai-discoverability", "admin-tool-inventory", "doozer-digest", "email-tracking", "identity-and-auth", "doozer-comms", "regeneration", "atlas", "gatherings-and-social", "livemusictonight", "elks-root-theme", "niche-color-system", "enrichment-store-links", "user-hotspots", "postcards", "cloud-headers", "hosting-infrastructure", "admin-health-tools", "dev-api", "free-tier-render-gotchas", "the-521-root-cause", "shortlinks-and-qr", "source-of-truth-cache", "postcard-targeting", "fact-guard-identity-numbers", "context-city-poisoning", "site-creation", "content-generation-and-heal", "deployment", "spotcheck", "implicit-verification", "no-dark-patterns-ethos", "icon-taste-rule", "magellan-id-mapping", "seo-cliff-recovery", "muse", "cloud", "family", "niche", "magellan-and-feeds", "niche-matching-and-discovery", "two-gates-and-the-catalog", "photo-pipeline", "the-muse-v2-layer", "events-to-machines", "the-doozer-score", "writer-model-and-accuracy", "the-now-surface", "doozer-town", "chamber-chamber" ], "status": "", "generated": null, "verified": [], "stale_after": "", "sources": [], "body": "# The Doozer Brain\n\nThis is Doozer's knowledge in [Open Knowledge Format](decisions/okf-adoption.md) (OKF):\nplain markdown files with YAML frontmatter, linked to each other to form a knowledge\ngraph. It is the durable \"brain\" behind the platform, and it is meant to be\n**self-contained**: an AI (or a person) reading this bundle should come away\nunderstanding the whole Doozer world — the idea, the direction, the processes, and\nthe value. It is additive to `MEMORY.md` (fast recall) and `CLAUDE.md` (project\ninstructions); see [how to grow this brain](AGENTS.md).\n\n**Just upgraded to a new model?** Read **`NOTES-FOR-NEWEST-MODEL.md`** (repo root) first —\nthe living handoff letter from the previous model — then follow the reading order below.\nSee [The model handoff](processes/model-handoff.md) for the tradition.\n\n**New session? Read [Start here — working with Jon](working-with-jon.md) first** — the\nportable working agreement: how we work, the house style, keeping a brain, the admin\nskeleton, the dev channel, and the stack that's only a key away. (A verbatim portable\ncopy is at `docs/start-here-working-with-jon.md`.)\n\n## Start here (read in this order)\n\n1. [The Mission](decisions/the-mission.md) — why Doozer exists + the non-negotiable\n quality bar (trusted / working / accurate / tasteful / useful / good).\n2. [The Doozer Story](decisions/the-doozer-story.md) — the origin and the idea.\n3. [The Architecture](systems/architecture.md) — one `index.php` serving unlimited\n sites; what a Doozer site actually IS.\n4. [The Network](systems/the-network.md) — every product in the ecosystem and how\n they interconnect (the breadth).\n5. [The Value Model](decisions/the-value-model.md) — how value is created and\n captured (the economics).\n6. [The Flywheel](systems/the-flywheel.md) — how it all compounds.\n7. [Doozer vs Doozer+](decisions/two-tier-model.md) — the free/paid direction.\n8. [The Observed World](decisions/the-observed-world.md) — render-on-demand: every\n local business exists once observed, and each materialized site is both inventory\n and a pre-built lead (the self-funding flywheel).\n\n## Organization\n\n- **craft/** — [the clever parts](craft/index.md): the non-obvious details that make\n Doozer different, where the interesting thing is the WHY.\n [Category-aware call intent](craft/category-aware-call-intent.md),\n [the hostile CSS environment](craft/hostile-css-environment.md),\n [skeleton first, index later](craft/skeleton-first-index-later.md),\n [self-healing email backfill](craft/self-healing-email-backfill.md),\n [price the pull before you pull](craft/price-the-pull-before-you-pull.md),\n [fix the source, not the symptom](craft/fix-the-source-not-the-symptom.md),\n [inline the bytes, not the proxy URL](craft/inline-the-bytes.md),\n [cross-root identity](craft/cross-root-identity.md),\n [derive the URL, don't store it](craft/derive-dont-store-the-active-domain.md),\n [the logo knows its own shape](craft/adaptive-logo-shape.md),\n [the distraction problem](craft/the-distraction-problem.md),\n [decision vs delivery](craft/decision-vs-delivery.md). A growing genre.\n- **systems/** — how things work:\n [Architecture](systems/architecture.md), [The Network](systems/the-network.md),\n [NearByMeNow](systems/nearbymenow.md), [Network Growth (\"More places nearby\")](systems/network-growth.md),\n [Clouds](systems/clouds.md),\n [Directory multi-view framework](systems/directory-framework.md),\n [Muse System](systems/muse-system.md), [Design Standards](systems/design-standards.md),\n [The Brand System (ecosystem identity kit)](systems/brand-system.md),\n [content generation pipeline](systems/content-generation.md),\n [Best AI for the Job (value-aware model selection)](systems/best-ai-for-the-job.md),\n [Fact-Guard](systems/fact-guard.md),\n [per-location data enrichment](systems/location-data-enrichment.md),\n [Weather Widget](systems/weather-widget.md),\n [shared business card](systems/shared-business-card.md),\n [section framework](systems/section-framework.md),\n [Lead Capture](systems/lead-capture.md), [LeadBuilder](systems/leadbuilder.md),\n [billing](systems/billing.md), [Money Clouds (affiliate)](systems/money-clouds.md),\n [Prospector](systems/prospector.md), [Marketing](systems/marketing.md),\n [Shortlinks + QR (doozer.link)](systems/shortlinks.md),\n [**The Growth Engine — the acquisition + monetization map**](systems/growth-engine.md),\n [AI Postcards (Factory + Theme Studio + campaigns)](systems/ai-postcards.md),\n [Thanks.io connector (direct mail, two-way)](systems/thanksio.md),\n [Promo Codes + the one-time claim offer](systems/promo-and-offers.md),\n [Hot Leads — internal Doozer-sales CRM](systems/doozer-prospects.md),\n [Machi (the marketing brain)](systems/machi.md),\n [Event Feeds (Marquee + the multi-source plan)](systems/event-feeds.md),\n [IndexNow (instant Bing crawl)](systems/indexnow.md),\n [AI Discoverability (llms.txt + AI-crawler welcome)](systems/ai-discoverability.md),\n [Admin Tool Inventory (audit + cockpit)](systems/admin-tool-inventory.md),\n [Doozer Digest](systems/doozer-digest.md),\n [Email Open Tracking](systems/email-tracking.md),\n [Identity + Auth](systems/identity-and-auth.md),\n [Doozer Comms (Telegram)](systems/doozer-comms.md),\n [Regeneration + Foundation](systems/regeneration.md),\n [Atlas (outward AI)](systems/atlas.md),\n [Gatherings + Social](systems/gatherings-and-social.md),\n [Live Music Tonight](systems/livemusictonight.md),\n [The Elks Root Theme](systems/elks-root-theme.md),\n [Niche Color System](systems/niche-color-system.md),\n [Enrichment Store Links](systems/enrichment-store-links.md),\n [per-user hotspots](systems/user-hotspots.md), [Postcards](systems/postcards.md),\n [cloud headers](systems/cloud-headers.md),\n [hosting infrastructure](systems/hosting-infrastructure.md),\n [Admin Health Tools](systems/admin-health-tools.md),\n [Dev API + Site Quality Score](systems/dev-api.md),\n [free-tier render gotchas](systems/free-tier-render-gotchas.md),\n [the 521 root cause](systems/the-521-root-cause.md),\n [shortlinks and QR (doozer.link)](systems/shortlinks-and-qr.md),\n [source-of-truth cache](systems/source-of-truth-cache.md),\n [postcard targeting](systems/postcard-targeting.md),\n [fact-guard: org identity numbers](systems/fact-guard-identity-numbers.md),\n [context-city poisoning](systems/context-city-poisoning.md),\n and [the flywheel](systems/the-flywheel.md).\n- **processes/** — how we do things: [site creation](processes/site-creation.md),\n [content generation and healing](processes/content-generation-and-heal.md),\n [deployment](processes/deployment.md), [the model handoff](processes/model-handoff.md),\n [spotcheck](processes/spotcheck.md).\n- **decisions/** — load-bearing calls: [the mission](decisions/the-mission.md),\n [the value model](decisions/the-value-model.md),\n [Doozer vs Doozer+](decisions/two-tier-model.md),\n [the observed world](decisions/the-observed-world.md),\n [implicit verification](decisions/implicit-verification.md),\n [no dark patterns](decisions/no-dark-patterns-ethos.md),\n [icon taste rule](decisions/icon-taste-rule.md),\n [Magellan ID mapping](decisions/magellan-id-mapping.md),\n [the SEO cliff and recovery](decisions/seo-cliff-recovery.md),\n [the Doozer story](decisions/the-doozer-story.md),\n [OKF adoption](decisions/okf-adoption.md).\n- **glossary/** — the vocabulary: [Muse](glossary/muse.md), [Cloud](glossary/cloud.md),\n [Family](glossary/family.md), [Niche](glossary/niche.md).\n\nThe live **network** (businesses, niches, clouds, families) is emitted as OKF nodes\non demand by `includes/okf-engine.php`, browsed in Admin → Doozer Brain, and\nprojected outward per-entity as the [Atlas](systems/atlas.md). The whole bundle\nexports as one portable `.zip` (Admin → Doozer Brain → Export). No secrets live in\nthe brain by design.\n- [Magellan and the feed pond](systems/magellan-and-feeds.md) — bound external IDs (`business_id_map`) + the gcal/elks_org adapters that make sites living entities.\n- [Niche matching and live discovery](systems/niche-matching-and-discovery.md) — a niche page matches OUR tag OR Google's `types`; a niche slug is NOT a place type; the thing you asked for is never junk.\n- [Two gates, and the category catalog](systems/two-gates-and-the-catalog.md) — directory visibility vs index eligibility; the promotion step that was never written; `dz nichecatalog`.\n- [The photo pipeline](systems/photo-pipeline.md) — references are free, bytes are bought once on first view; the cache key is `md5(name + w/h)` so WIDTH is part of it, and any page can ask \"do we already own this?\" before spending. `dz imgct`.\n- [The Muse v2 layer](systems/the-muse-v2-layer.md) — the v2 render layer never applied to ANY site (token array passed where a muse row was expected); a muse is only as good as its brief. `dz muse do=tokens`.\n- [Events to machines](systems/events-to-machines.md) — a live event is only half published until a machine can read it; the schema.org Event pipeline + the timezone rule.\n- [The Doozer Score](systems/the-doozer-score.md) — Stick (cost per 100 sites), Tower (value per 100), and the leverage between them.\n- [The writer model is chosen on accuracy](decisions/writer-model-and-accuracy.md) — gpt-5.4-mini, decided by an 11-niche bake-off after the pricier model fabricated a fact.\n- [The /now surface](systems/the-now-surface.md) — one button, the nearest places, Build-it-on-the-spot; plus the measured teardown of the category page.\n- [Doozer Town and the Board Game view](systems/doozer-town.md) — self-building town clouds on doozer.town (slug = the instruction, $0 from inventory, one gated geocode otherwise), ten colour groups, any cloud as a property board.\n- [The Chamber Chamber and doozer.world](systems/chamber-chamber.md) — thechamberchamber.com is Directory Harvest's public face (roster read once, dated, sourced; members connected to their Doozer pages; emails never shown); doozer.world is the two-screen front door with thirteen honestly-labelled doors." }, { "id": "okf-adoption", "title": "Adopt Open Knowledge Format for the Doozer brain", "type": "Decision", "group": "decisions", "description": "Why Doozer organizes its knowledge as an OKF bundle, scoped to the stable core.", "tags": [ "okf", "knowledge", "decision" ], "path": "decisions/okf-adoption.md", "links": [ "deployment", "AGENTS", "the-flywheel", "implicit-verification" ], "status": "", "generated": null, "verified": [], "stale_after": "", "sources": [], "body": "# Adopt Open Knowledge Format for the Doozer brain\n\n**Decision (June 2026):** organize Doozer's internal knowledge as an\n[Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog)\nbundle (this `knowledge/` directory) and build exploration tools on it.\n\n## Why\n\n- OKF is \"just files\": markdown + YAML frontmatter in a typed tree, with markdown links\n as graph edges. Vendor-neutral, SDK-free — a perfect fit for Doozer's\n [FTP / no-env model](../processes/deployment.md).\n- Doozer already speaks it: the memory topic files are frontmatter-markdown, `docs/` is\n categorized markdown, and `includes/design-md.php` already emits and serves\n OKF-shaped `/design.md` artifacts.\n- It gives a durable, linkable \"brain\" beyond the flat `MEMORY.md` index — usable by\n agents (future Claude) and humans alike.\n\n## Scope and caveats\n\n- Adopt the STABLE core (markdown + frontmatter + links). OKF is v0.1, so do NOT couple\n to Google's Knowledge Catalog ingestion yet.\n- The brain is ADDITIVE: `CLAUDE.md` (instructions) and `MEMORY.md` (recall index) keep\n their roles. See [how to grow the brain](../AGENTS.md).\n- Engine: `includes/okf-engine.php` parses this bundle, emits the live network as OKF\n nodes ([the flywheel](../systems/the-flywheel.md)'s data), and exports a portable zip.\n Explorer: Admin → Doozer Brain.\n\n## Branding: OKF is plumbing, Doozer Atlas is the product\n\nThe outward, AI-native emission layer is branded **Doozer Atlas** (real-world entities\ncontinuously emitting machine-readable knowledge). OKF and schema.org JSON-LD are\n*exports* of that layer, not the product. Pairs with the **Doozer Brain** (internal\nknowledge) as Brain (inward) vs Atlas (outward). The per-entity public endpoint is\n`/.well-known/doozer-atlas` (`format: doozer-atlas/0.1`); see\n[the flywheel](../systems/the-flywheel.md).\n\n## Atlas principles (the guardrails)\n\n1. Atlas emits facts, not hallucinations. AI is a CONSUMER of Atlas, not its source.\n2. Public information only. Never private contact data.\n3. Relationships are first-class objects (CONTAINS, DISCOVERABLE_IN, LOCATED_IN,\n IN_NICHE, NEARBY, COVERS_NICHE/PLACE, HOSTS_EVENT). Density is the long-term moat,\n but only emit edges DERIVED from real data, never invented.\n4. Atlas exists automatically for every Doozer host (business, cloud, root, VD).\n5. **Every field must justify its existence**: \"will this help a human, AI, or another\n Doozer system understand the world around this entity?\" If no, do not emit it. Keep\n Atlas small and intentional, not a dumping ground.\n6. Provenance is the differentiator: per-field source + an owner-verified tier (tied to\n [implicit verification](implicit-verification.md)) is trust infrastructure nobody can\n copy. Strengthen it over time (confidence, verified_at).\n\nArchitecture note: Atlas OWNS THE CONTRACT, not the storage. It is a DERIVED projection\nover the source-of-truth tables (always fresh, no migration, no dual-write). OKF /\nschema.org / the `/.well-known/doozer-atlas` JSON are exports of the same model. Resist\n\"Atlas owns a graph DB\" and \"site renders FROM Atlas\" (a rewrite); evolve, don't rebuild.\n\n## Deferred (roadmap)\n\nPublic publishing (`/knowledge.md` + a public explorer), a build-in-public marketing\nbeat, and a self-growing enrichment agent." }, { "id": "two-tier-model", "title": "Doozer vs Doozer+ (the two-tier model)", "type": "Decision", "group": "decisions", "description": "The product direction splitting a free templated info page from a paid bespoke full site, and why the split exists.", "tags": [ "direction", "strategy", "doozer-plus", "tiers", "product" ], "path": "decisions/two-tier-model.md", "links": [ "architecture", "muse", "family", "section-framework", "billing", "no-dark-patterns-ethos", "lead-capture", "the-value-model" ], "status": "", "generated": null, "verified": [], "stale_after": "", "sources": [], "body": "# Doozer vs Doozer+\n\nDecided July 2026. Doozer splits into two tiers that share the same\n[engine and data spine](../systems/architecture.md) but differ in ambition and\nprice.\n\n## Free — Doozer\n\nA **templated info page** the business owns: generated from Places data + reviews +\nenrichment, styled by a [Muse](../glossary/muse.md) drawn from the shared\n[family library](../glossary/family.md), assembled from the standard\n[section framework](../systems/section-framework.md). The free tier's job is to be\n*trusted, working, accurate, tasteful, useful, and good* out of the box, at fleet\nscale, for zero cost to the business. This is what 2,400+ live sites run today. The\nfree-tier rebuild (families/archetypes/structure hardening) is ongoing.\n\n## Paid — Doozer+\n\nA **bespoke full site**: a richer render layer (\"Muse+\") on the same spine, for\nbusinesses that upgrade via [Stripe billing](../systems/billing.md). Doozer+ is the\n\"WordPress-killer\" ambition: multi-section, distinctive, effectively hand-quality,\nwithout a human building it. It is a **separate render layer**, not a reskin of the\nfree page, so the free tier can stay lean while Doozer+ goes deep.\n\n## Why split\n\n- **Different jobs.** The free page must be reliable and uniform-good across the\n whole fleet; the paid site must be singular and impressive. Optimizing one layer\n for both compromised both.\n- **Honest upgrade path.** The free site is genuinely useful, so the upgrade is a\n real step up, not a crippled-teaser-to-usable jump. No\n [dark patterns](no-dark-patterns-ethos.md).\n- **Value capture follows value.** Free creates presence + [leads](../systems/lead-capture.md);\n Doozer+ captures the businesses that want more. See\n [the value model](the-value-model.md).\n\nShared spine, two render layers. A business is never rebuilt from scratch to move\nbetween tiers: same inputs, richer output." }, { "id": "icon-taste-rule", "title": "Icon Taste Rule", "type": "Decision", "group": "decisions", "description": "Primary UI uses crafted SVG icons, never clipart/emoji; color is reserved for state, not for buttons.", "tags": [ "design", "icons", "taste" ], "path": "decisions/icon-taste-rule.md", "links": [ "shared-business-card", "no-dark-patterns-ethos", "design-standards" ], "status": "", "generated": null, "verified": [], "stale_after": "", "sources": [], "body": "# Icon Taste Rule\n\n**Decision (operator, June 2026):** primary and structural UI uses CRAFTED SVG icons\n(stylish, on-brand), NEVER default plain emoji or clipart. Emoji is acceptable only as\na playful inline accent (for example the call-intent chips in a popup), not as primary\niconography.\n\nCorollary on the [shared business card](../systems/shared-business-card.md): card\noverlay icons are neutral white on the dark translucent circle; **color is reserved for\nSTATE** (a saved heart is red, a checked-in pin is green), never for the buttons\nthemselves. Tried colored outlines, reverted — color-as-state reads better and scales\nas more actions are added.\n\nSame family of taste calls as [no dark patterns](no-dark-patterns-ethos.md) and\n[Design Standards](../systems/design-standards.md): the product should never look cheap\nor machine-stamped." }, { "id": "implicit-verification", "title": "Implicit Verification (no claim system)", "type": "Decision", "group": "decisions", "description": "Business ownership is an email match, not an account/claim flow. Load-bearing platform architecture.", "tags": [ "auth", "ownership", "decision" ], "path": "decisions/implicit-verification.md", "links": [ "no-dark-patterns-ethos", "the-flywheel" ], "status": "", "generated": null, "verified": [], "stale_after": "", "sources": [], "body": "# Implicit Verification\n\n**Decision:** a business owner is recognized by an email match, with no claim system,\nno verification queue, no support tickets.\n\n```php\n// admin_email is AUTHORITATIVE once set; the scraped email is only the\n// implicit owner while UNCLAIMED. (Refined v2.2.396 — see the lock below.)\n$isBusinessAdmin = $business->admin_email\n ? ($user->email === $business->admin_email)\n : ($user->email === $business->email);\n```\n\n- `businesses.email` — the scraped canonical contact email (public). Grants ownership\n ONLY while the listing is unclaimed (`admin_email` empty).\n- `businesses.admin_email` — the claimed / operator-set owner (never shown publicly).\n Set by a redeemed claim code or by Doozer staff. Solves the agency case: one\n `admin_email` across many businesses = one login to manage many.\n\n**The claim lock (v2.2.396).** Originally ownership was `email OR admin_email` — which\nlet a listing have TWO owners at once: whoever controlled the scraped inbox AND a\ndifferent person who redeemed a claim code. Now, once `admin_email` is set the listing\nis **locked to that email**: the scraped email no longer grants ownership, and a claim\ncode from a different email is refused (it cannot take over). The redeemed code records\n`redeemed_by_email` (attached to who used it). To CHANGE the email on a claimed listing\nthe owner must **request a new code**, mailed to the business address (operator voids\nthe old + clears `admin_email` so the new code can bind). The ownership test lives in\nONE place: `businessIsClaimedByViewer` / `businessOwnerAccount` (`premium.php`); the\nredeem guard is in `claimCodeRedeem` (`claim-codes.php`).\n\nLogin is the existing magic-link flow (`lb_users` / `currentUser()`); when the email\nmatches either column, the avatar dropdown reveals \"Manage [Business]\". Self-healing\nemail backfill: repeated visits from one fingerprint enqueue a priority scrape that\ntries harder to find a contact email, so \"I tried last week, it didn't work; today it\ndoes.\"\n\nA three-tier education affordance (footer utility row, an about-this-listing page, a\nsoft heuristic nudge) explains the model without nagging. This embodies the\n[no dark patterns](no-dark-patterns-ethos.md) ethos and underpins owner-facing parts of\n[the flywheel](../systems/the-flywheel.md)." }, { "id": "magellan-id-mapping", "title": "Magellan — cross-service business identity mapping", "type": "Decision", "group": "decisions", "description": "Doozer cross-links businesses by verified external IDs (Google Place, Ticketmaster, future services), never by name/city/state. Magellan is the mapping spine. Decided June 2026; not yet built.", "tags": [ "magellan", "identity", "ids", "architecture", "data-driven", "marquee", "atlas" ], "path": "decisions/magellan-id-mapping.md", "links": [ "livemusictonight" ], "status": "", "generated": null, "verified": [], "stale_after": "", "sources": [], "body": "# Magellan — cross-service business identity mapping\n\n**Decision:** Doozer is a data-driven ecosystem. A business is cross-linked to any external\nservice by its **verified ID for that service**, never by matching name + city + state. The\nmapping layer is **Magellan**.\n\n## Why\n\nName/city/state matching guesses (\"The Stone Pony\" vs \"Stone Pony\"), produces duplicates, and\nbreaks silently. Every business already has a Google Place ID; venues built from\n[Marquee](../systems/livemusictonight.md) have a Ticketmaster venue ID. The reliable join is\nthe ID. Magellan makes that the only join.\n\n## What Magellan does\n\n- Maps each Doozer `businesses.id` to its identity in every service it participates in:\n Google Places, Ticketmaster, and any future API/resource.\n- Knows the **expected** set of IDs for a business (from its origin/niche) — a Marquee music\n venue must have a TM id; a discovery-built plumber need not — and reports the gaps.\n- Surfaces mapping issues: missing-but-expected, conflicts, duplicates, unverified.\n- Lets the operator search + tag IDs **without knowing any raw ID** (resolve by\n name → candidate lookup → confirm, or pull from the service's own API).\n- Every build path writes its known IDs at creation; the [Atlas](../systems/livemusictonight.md)\n emits them as entity identifiers so AI/agents cross-reference the same way.\n\n## Shape (intended, not built)\n\nA `business_id_map` join table — `(business_id, service, external_id, source, confidence,\nverified_at)`, unique per `(business_id, service)`, indexed on `(service, external_id)` for\nreverse lookups — generalizing the existing hot columns `businesses.google_place_id` and\n`businesses.tm_venue_id`. Backfill from those; then retire the name-match fallback in\n`_vdLinkVenues`.\n\nStatus: **directive recorded, not built.** See `project_magellan` in the memory layer." }, { "id": "no-dark-patterns-ethos", "title": "No Dark Patterns (the Doozer ethos)", "type": "Decision", "group": "decisions", "description": "Pure intent, organic, intelligence-driven. The lens for every product and ranking decision.", "tags": [ "ethos", "principles", "decision" ], "path": "decisions/no-dark-patterns-ethos.md", "links": [ "implicit-verification", "design-standards", "icon-taste-rule" ], "status": "", "generated": null, "verified": [], "stale_after": "", "sources": [], "body": "# No Dark Patterns\n\nThe guiding ethos. Doozer is built with **pure intent**: no popups, no deceptive ads or\ntechniques, no malware, no junk. \"Like shopping in the organic aisle.\" Intelligence is\nused to find the diamonds in the rough and the needles in the haystack, and to serve the\ntwo parties that matter: the customers and the businesses.\n\nThis is the lens for product AND ranking decisions, not a single feature. It connects to:\n\n- [Implicit verification](implicit-verification.md) — no account walls, no claim\n upsell; we recognize owners and help them.\n- [Design Standards](../systems/design-standards.md) — tasteful, readable, never\n AI-slop; fix root causes, not bandaids.\n- The mission: a *new web* in the GeoCities spirit, safe and useful, every site its own.\n\nSibling rules with the same spirit: the [icon taste rule](icon-taste-rule.md), and \"no\nem dashes in user-visible copy\" (so it does not read as machine-written)." }, { "id": "the-cloud-fabric", "title": "The Cloud Fabric — automatic clouds over the observed network", "type": "Decision", "group": "decisions", "description": "The connective-tissue vision. Once every local business exists as a Doozer site (observed / painted on demand), Clouds form automatically around topic, area, and non-obvious relationships, cross-linked into one self-reinforcing, claimable, quality-indexed network that serves both businesses and users.", "tags": [ "clouds", "strategy", "network", "observed-world", "real-estate", "awesomeaddresses", "seo", "magellan", "thanksio", "cross-linking" ], "path": "decisions/the-cloud-fabric.md", "links": [ "the-observed-world", "the-value-model", "seo-cliff-recovery", "the-mission", "thanksio", "project_new_roots_roadmap", "project_prospector_status", "project_magellan" ], "status": "", "generated": null, "verified": [], "stale_after": "", "sources": [], "body": "# The Cloud Fabric\n\n**Captured with Jon, Jul 7 2026.** The strategic thesis that ties the whole\nnetwork together. Read alongside [the observed world](the-observed-world.md),\n[the value model](the-value-model.md), [SEO cliff](seo-cliff-recovery.md), and\n[the mission](the-mission.md).\n\n## The mental model\nAssume every local business already has a Doozer site — \"painted on demand\" the\nmoment it is observed (the observed-world pivot). Once that is the substrate,\nthe interesting value is not the individual page, it is the **relationships\nbetween pages**. Those relationships are Clouds.\n\nClouds form around three axes, and the third is the differentiator:\n1. **Topic** — food, bowling, golf, arcades, garden centers, specialty markets,\n farmers markets, churches, shopping, services. Any niche, any grain.\n2. **Area** — a town, a county, a region.\n3. **Non-obvious connection** — the businesses you need *together* for a real\n task, even across niches. This is the insight.\n\n## The load-bearing example: the real-estate transaction\nThe businesses you touch buying a home are not one niche — they are a workflow:\nrealtor's office → real estate lawyer → title / escrow agency → town hall →\ncounty clerk → local post office → and \"where do we eat lunch in our new town.\"\nThat bundle is a Cloud. Two shapes:\n- **Personal** — a buyer's private bookmark cloud for *their* transaction (My\n Doozer Cloud over saved businesses), later including their favorite\n AwesomeAddresses homes.\n- **Public niche cloud** — a \"moving to \" / \"real estate in \" cloud\n any agent or buyer can use, per city/town, indexable and shareable.\n\nReal estate is also the **wedge for monetization**: realtors are heavy direct-\nmail buyers, so they are prime [Thanks.io](../systems/thanksio.md) claim / Doozer+\ntargets *now* (record_types onlybusinesses in a farm area, mail them their site).\nWhen [AwesomeAddresses](../../project_new_roots_roadmap.md) (Zillow-style\nresidential root) launches, the whole real-estate professional graph — listing\nagents, buyer agents, developers, brokers, title, lenders — becomes a first-class\naudience working inside that system.\n\n## Why this points at success (the compounding)\n- **Self-building** — observed-world paints the sites; Prospector / Cloud Factory\n / Thanks.io radius buys grow inventory without hand work.\n- **Clustered** — [Cloud Factory](../../project_prospector_status.md) already does\n niche+region → cloud + sweep + build + auto-join. Automatic + recipe-driven\n clouds are the next grain (multi-niche bundles like the transaction cloud).\n- **Cross-linked** — clouds are genuine internal links between real pages;\n [Magellan](../../project_magellan.md) makes every cross-link by stable ID, and\n domains/subdomains/roots interlink through shared chrome (network footer,\n neighborhood rails). Link equity flows where value is.\n- **Claimable + valuable** — every node is a pre-built lead; the CLAIM→EARN funnel\n turns attention into owners and Doozer+ revenue. Clouds raise the value of each\n node (context, referrals, \"more from the neighborhood\").\n- **Indexed** — clouds are legitimately useful, curated pages that deserve to rank.\n\n## The guardrails that decide success vs. cliff (do NOT skip)\n1. **Quality-gated indexing.** The [SEO cliff](seo-cliff-recovery.md) proved that\n mass-indexing thin, templated, scaled pages gets the WHOLE network\n algorithmically demoted. \"Indexed by search engines\" must mean: index only\n observed + enriched + genuinely useful pages and clouds; keep thin/unclaimed\n inventory out of sitemaps until it earns its place. Clouds help (curation +\n real internal links) ONLY if the clouds themselves are substantive, not empty\n niche×town permutations. Auto-cloud generation must have a content floor.\n2. **No slop, taste first** ([the mission](the-mission.md)) — a cloud with three\n junk members is worse than no cloud. Curation and a membership quality bar.\n3. **Cost discipline** ([[feedback_api_costs]]) — painting-on-demand and radius\n buys spend money; gate behind observation/demand, reuse cache, never mass-build\n speculatively.\n4. **Ethics** ([[project_doozer_ethos]]) — organic value, no dark patterns; mail\n and clouds must serve the business and the user, not trick either.\n\n## Packs — the multi-niche recipe (SHIPPED v2.2.375)\nA **pack** is a curated set of Google Places types that belong together by\nPURPOSE. `includes/cloud-packs.php` ships **31 hand-authored packs** referencing\nreal `niche_mappings.google_type` values, each with a **quality gate**\n(`min_reviews`, `require_location`, `min_rating`, and `open_247` for the 24/7\npack) and, where a single pro naturally owns the workflow, **keeper-eligibility**.\nExamples: Real Estate Transaction, Wedding, New in Town, Movers & Relocation,\nHome Improvement, Money & Advice, Final Arrangements (the 7 keeper packs), plus\nMe Time, Med Near Me, Lessons & Growth, Get Moving, New Parent, Pet Parent, Where\nto Eat, Coffee & Cowork, Sweet Tooth, Farm to Table, Date Night, Family Fun, Night\nOut, Fresh Air, On the Water, Green Thumb, Two Wheels, Local Boutique, Auto Care,\nInk & Adornment, Smoke & Vape, Culture & Books, Faith & Worship, Open 24 Hours.\n`cloudPackPreview($key,$city,$state)` is a COST-FREE count of existing Doozer\nmembers a pack would gather in a town, with a `meets_floor` flag — the content-\nfloor guard so we never build/index a thin pack cloud. Ops: `dz packs\nlist|keeper|show|preview|build|keeper_offer|set_keeper`. Membership = niche-set +\ngeo — the cloud engine already supports it (cloud_type=niche, `criteria.niches`\nis an array). **`cloudPackBuild($pack,$city,$state)` SHIPPED**: creates the live\ncloud at `--.doozer.cloud`, cost-free from existing members,\nidempotent, `fill=1` sweeps below-floor niches (`prDiscoverySweep`, confirm-gated).\nProven end to end (Real Estate / West Milford NJ, live). WATCH-ITEM: raise the\ncontent floor above the demo's 4 and gate INDEXING (sitemap) on a higher quality\nbar than build, so thin pack clouds render but do not get indexed until filled.\n\n## The Keeper — territorial exclusivity as the sale\nKeeper-eligible packs are monetized by **exclusivity**: one professional becomes\nthe KEEPER of that pack cloud in their city/region — their name, brand, and\nreferral position across the whole workflow bundle. One keeper per pack per\nterritory. The pitch (esp. realtors): \"Own the Real Estate cloud for your\nterritory. Every buyer and seller in town sees you first.\" Offer it to every pro\nin the farm area (Thanks.io radius, `record_types=onlybusinesses` + real estate\nniche); one takes it. Mechanically the Keeper = the cloud's paid sponsor/owner\n(clouds already carry `sponsor_name/url/logo` via `cloudSetSponsor`, and the\nobserved-world claim path grants ownership) sold as a Doozer+/premium position.\nAny realtor pitch MUST lead with claiming their territory — scarcity closes it.\n\n## Sequence (how we get there)\n- NOW: multi-niche **cloud recipes** (transaction cloud as the first) on the\n existing cloud engine + Cloud Factory; Thanks.io realtor claim campaigns; keep\n indexing quality-gated.\n- NEXT: automatic cloud formation (topic/area detection over observed businesses),\n personal transaction clouds in My Doozer Cloud.\n- LATER: AwesomeAddresses homes as cloud members + the full real-estate pro graph.\n\nThe direction is sound because the machinery mostly exists (observed-world, cloud\nengine, Cloud Factory, Magellan, claim funnel, Thanks.io). The work is composing\nit into recipes + automatic formation, and holding the quality/indexing line so\nthe network compounds instead of cliffs." }, { "id": "the-doozer-story", "title": "The Doozer Story", "type": "Decision", "group": "decisions", "description": "The canonical WHO/WHAT/WHEN/WHERE/WHY/HOW of Doozer, distilled. The single source the Postcards, landing copy, and press materials draw from.", "tags": [ "story", "brand", "mission", "canon" ], "path": "decisions/the-doozer-story.md", "links": [ "postcards", "okf-adoption", "muse-system", "the-flywheel" ], "status": "", "generated": null, "verified": [], "stale_after": "", "sources": [], "body": "# The Doozer Story\n\nThe distilled canon, written from June 2026. The expressive, evolving form is\n[Postcards](../systems/postcards.md); this is the spine they hang on.\n\n**WHO.** Doozer is a BerrySmart product, built by one person: Jon Berry, solo founder and\noperator, hands-on and technical. Named after the tireless little builders from Fraggle\nRock. Each Cloud has a Keeper; NearByMeNow carries the traffic; the Muse gives each site\nits voice.\n\n**WHAT.** A domain-driven platform that turns unused or forwarded domains into useful,\nfindable single-page websites for real local businesses. One codebase, 2,400+ live sites,\nevery one different. Around it: NearByMeNow (directory), Doozer.Cloud (curated Clouds),\nmy.doozer.cloud (a person's saved places), and the coming GoHe.re (gatherings) and wuz.ai\n(memory) layers. LeadBuilder is a sibling. [Atlas](okf-adoption.md) makes it all legible\nto machines.\n\n**WHEN.** Built around turning fifty, as a swan-song legacy project, in the margins of a\nfull life: early mornings and late nights, between full-time work and raising a family.\nAnd built for a specific moment in history: when AI answer engines replaced the page of\nblue links and the question changed from \"what ranks\" to \"what gets cited.\"\n\n**WHERE.** Bootstrapped, no outside funding, answerable only to its users and its\nstandards. Deployed by hand from a laptop. No office, no team. The whole company fits in\na backpack.\n\n**WHY.** Local businesses should not lose to AI; they should be found by it. The bakery,\nthe welder, the tailor, the lodge hold neighborhoods together and are exactly the ones\nleast likely to have a current site, which now means least likely to be found. Doozer\npoints the same AI the other way. The bar is taste: useful, accurate, tasteful, no dead\nends, no AI-slop, no dark patterns. \"We Build Because.\"\n\n**HOW.** One codebase; the site is built on the fly from the domain used to reach it.\nSix steps, most under a minute: point, find (Google Places), enrich, match (a\n[Muse](../systems/muse-system.md) from a library of 100), compose (AI prose plus a guarded\nlayout pipeline), improve (every signal feeds back). Written to self-heal, because usually\nno one is watching.\n\n**VISION.** Seven surfaces, one universe, a [flywheel](../systems/the-flywheel.md) where\neach layer makes the next more valuable. The real, local, physical world deserves a web\nthat is on its side. Built one careful piece at a time." }, { "id": "the-mission", "title": "The Mission (the north-star quality bar)", "type": "Decision", "group": "decisions", "description": "Why Doozer exists and the non-negotiable quality bar every site must clear — the lens for every build decision.", "tags": [ "mission", "quality", "north-star", "values", "why" ], "path": "decisions/the-mission.md", "links": [ "fact-guard", "lead-capture", "location-data-enrichment", "muse-system", "design-standards", "no-dark-patterns-ethos", "the-value-model" ], "status": "", "generated": null, "verified": [], "stale_after": "", "sources": [], "body": "# The Mission\n\nDoozer is BerrySmart's (Jon Berry's) legacy work: a serious attempt to give every\nsmall business a web presence that is genuinely good, generated automatically, at a\nscale and price no human-built approach can match. It is built with pure intent,\nnot extraction. The tagline is **\"We Build Because.\"** (never invent others).\n\n## The quality bar (non-negotiable)\n\nA site ships only if it is all of:\n\n- **Trusted** — accurate, honest, no misinformation. See [fact-guard](../systems/fact-guard.md).\n- **Working** — fast, live, no broken states, no [dead ends](../systems/lead-capture.md).\n- **Accurate** — reflects the real business, [GIGO](../systems/location-data-enrichment.md).\n- **Tasteful** — distinctive and dignified, never templated slop. See the\n [Muse system](../systems/muse-system.md) and [design standards](../systems/design-standards.md).\n- **Useful** — answers the visitor's real question.\n- **Good** — the kind of thing you would be proud to have your name on.\n\n\"No dead ends, no slop\" is the shorthand. A page that looks AI-generated (em-dashes,\nbanned phrases, generic layout) fails \"tasteful.\" A lead with nowhere to go fails\n\"working.\" A wrong lodge number fails \"trusted.\"\n\n## The ethos\n\nNo dark patterns, ever ([the ethos](no-dark-patterns-ethos.md)). The intelligence\nof the platform is aimed at finding the diamonds and needles for real people, a new\nway to think about the web: discovery and presence in service of the visitor and\nthe business, not manipulation. [Value](the-value-model.md) is captured honestly,\ndownstream of value genuinely created.\n\nThis is the lens. When a build decision is ambiguous, choose the option that keeps\nthe site trusted, working, accurate, tasteful, useful, and good. Read this before\nbuilding." }, { "id": "the-observed-world", "title": "The Observed World (render-on-demand + the lead flywheel)", "type": "Decision", "group": "decisions", "description": "Doozer already contains every local business in spirit; a site or cloud becomes real only when observed. Each materialized site is simultaneously inventory and a pre-built lead. This reframes what to build, what to measure, and how money is made.", "tags": [ "strategy", "observed-world", "quantum", "lead-flywheel", "revenue", "seo", "why" ], "path": "decisions/the-observed-world.md", "links": [ "network-growth", "clouds", "seo-cliff-recovery", "the-mission", "no-dark-patterns-ethos", "implicit-verification", "lead-capture", "prospector", "two-tier-model", "billing", "atlas", "money-clouds", "growth-engine", "the-value-model" ], "status": "", "generated": null, "verified": [], "stale_after": "", "sources": [], "body": "# The Observed World\n\n## The premise\n\nBecause of the [More Places Nearby](../systems/network-growth.md) expansion, the\nDoozer ecosystem creeps outward to include every nearby business, especially\nwithin niche: restaurants, laundromats, real estate offices, gas stations, all\nof it. View this as a live-painted world, the way an RPG renders only the pixels\nthe player can see while a whole world of data stands behind them. **Doozer, in\nspirit, already holds a directory of every local business.** A site — or a\n[cloud](../systems/clouds.md) — exists the moment it is observed. It is, in a\nway, already there.\n\nThe engine for this already exists: `resolvePlaceToEcosystem`\n([place-resolver](../systems/network-growth.md)) is skeleton-first,\nmaterialize-on-observe, defer-enrichment. The shift is mental: **stop treating\n\"sites we have built\" as the inventory.** The inventory is every business that\n*could* be rendered; built sites are just the observed, cached subset.\n\n## The two assets in one act\n\nEvery business More Places Nearby materializes is at once:\n\n1. **Inventory** — a pixel in the observed world (coverage, SEO surface, and the\n substrate AI agents can query).\n2. **A pre-built lead** — a finished, live product sitting on a real business's\n doorstep that they have never seen.\n\nConcept one manufactures the inventory. Concept two monetizes each unit. Revenue\nfrom the sales funds the enrichment that makes the inventory real. It is a\nself-funding loop (see the flywheel diagram this node was captured from).\n\n## The two gates (load-bearing)\n\nInfinite coverage has two failure modes; one rule closes each.\n\n- **The observation / SEO gate.** Doozer already took an algorithmic\n scaled-content demotion once ([SEO cliff](seo-cliff-recovery.md)). NEVER\n pre-render the latent world into crawlable pages. A page becomes real\n (indexable, enriched) only when a genuine observer earns it. Done this way the\n observed-world model is the *antidote* to the cliff, not a bigger version of\n it — every indexed page has a real reason to exist.\n- **The pride / quality gate.** A latent world of thin skeletons is worthless and\n would embarrass the brand, against the [mission](the-mission.md) and the\n [no-dark-patterns ethos](no-dark-patterns-ethos.md). The observation itself\n triggers enrichment proportional to interest, and no site is mailed or pitched\n until it passes a quality bar. The two gates force the machine into quality.\n\n## The lead flywheel (how the money starts)\n\nDoozer inverts the SaaS funnel: **the site is live before the pitch.** Not \"sign\nup and we will build it,\" but \"this is your website, it is already working, claim\nit.\" Mostly assembly, because the pieces exist:\n\n- **The email is the login.** [Implicit verification](implicit-verification.md)\n says `user.email === business.email` → business admin, no claim system. So\n every [lead-routing email](../systems/lead-capture.md) Doozer already sends is\n the pitch: log in with this address to claim the listing and manage leads.\n- **QR + direct mail.** The [Places address is on file](../systems/prospector.md);\n Thanks.io mails a postcard with a QR to the live site. Instant gratification:\n scan, see it, sold.\n- **Billing is wired.** Upgrade to [Doozer+](two-tier-model.md) at $99/yr via\n [Stripe billing](../systems/billing.md).\n\nEconomics work at trivial conversion: a postcard is well under a dollar; $99/yr\nneeds ~1–2% to be strongly positive, and the lead-email funnel is nearly free.\nEvery new site from More Places Nearby drops a fresh prospect into the funnel —\nwhich is exactly what the new-site ping already fires on.\n\n## What changes\n\n- **Metrics.** Stop counting sites built (vanity, and past a point an SEO\n liability). Count **observations served** and **businesses claimed**.\n- **Product identity.** Doozer is not a website builder; it is the rendering\n engine for the local commercial world.\n- **Tools this implies** (not yet built): a unified **Demand Ledger** (fold\n `search_demand` + `lmt_interest` + GSC impressions + nearby-taps + name-404s)\n that decides what to paint next and what is safe to index; **build-on-query**\n as the front door; **cloud-on-demand** criteria directories; a **reality\n meter** per entity (how much real signal backs this pixel, gating index and\n mail); and the [Atlas](../systems/atlas.md) extended into a queryable / MCP\n surface so AI agents — the new observers — can ask \"does Doozer have X?\" and\n always get \"yes, here it is.\" Being the local layer AI agents cite and route\n through may be a bigger business than the sites.\n- **Revenue paths:** claim/upgrade on materialized sites; affiliate\n [money clouds](../systems/money-clouds.md) conjured on demand; API/agent access\n to the queryable world; the demand ledger itself as market intelligence.\n\n## Build order (cheapest-first)\n\n1. **Step 0 — claim CTA in lead emails. SHIPPED v2.2.355.** `nbmnLeadEmailBusiness()`\n appends a \"claim your listing\" block (their live site + the email-is-the-key\n pitch); the [claim landing](../systems/lead-capture.md) at `?page=claim&b=`\n (`includes/claim-listing.php`) shows the owner their live site and offers a\n one-step magic-link login (existing `claim` purpose + `?ajax=magic_link_send`),\n with a soft Doozer+ $99/yr upsell.\n **The CLAIM to EARN half, shipped v2.2.371.** A claim now delivers real value\n and the upgrade actually bills. (a) Enrichment surfaces the scraped\n `contact_email` onto the empty `businesses.email` column\n (`performBasicEnrichment`) — without this, an emailless-but-scraped business\n could never match on implicit verification, so no re-scan could ever unlock a\n claim. (b) `?page=plus` (`includes/plus-landing.php`) is a real Doozer+ page\n telling the two value stories and starting Stripe checkout (sku\n `premium_yearly`, $99/yr, code `LAUNCH20`); previously it dead-ended on the\n landing page. (c) Ads come off a page the moment it is claimed (an account\n exists for the contact/admin email) or when the owner is viewing —\n `businessAdsSuppressed()` + friends in `premium.php`, hooked into\n `business-site.php`'s `$showAdsense`. Ads are the monetization of UNCLAIMED\n inventory only. (d) `includes/manage-business.php` (`?page=manage&b=`,\n owner-gated) is the \"Manage your site and leads\" surface — ad-free\n confirmation, editable phone/website, leads inbox. (e) The claim page's\n non-match state has \"I added it, re-scan my site\" → `?ajax=claim_rescan`\n (priority `basic_enrichment`, rate-limited) so an owner can add their email\n and unlock the claim. Still NO claims table — \"claimed\" is derived from an\n `lb_users` email match, exactly the implicit-verification model.\n2. **Step 1 — QR + claim/upgrade landing** on top of existing Doozer+ / Stripe.\n3. **Step 2 — Thanks.io direct mail**, gated on the reality meter (only mail a\n site worth pride).\n4. **Alongside — the Demand Ledger**, the brain that says what to materialize and\n what is safe to index.\n\nCaptured July 5, 2026 (with Jon) as a strategic pivot to examine for value and\nrevenue. **Realized by [The Growth Engine](../systems/growth-engine.md)** — the\nconcrete observe→serve→convert→learn machine (postcards, offers, Hot-Leads CRM).\nRelated: [the value model](the-value-model.md),\n[two-tier model](two-tier-model.md), [SEO cliff](seo-cliff-recovery.md),\n[no dark patterns](no-dark-patterns-ethos.md)." }, { "id": "seo-cliff-recovery", "title": "The SEO Cliff and Recovery (why we noindex until quality-gated)", "type": "Decision", "group": "decisions", "description": "The May 2026 elks.club algorithmic demotion for scaled thin content, and the enrich-then-index discipline it burned into the platform.", "tags": [ "seo", "quality", "elks", "scaled-content", "noindex", "lesson" ], "path": "decisions/seo-cliff-recovery.md", "links": [ "network-growth", "location-data-enrichment", "muse-system", "regeneration", "fact-guard", "the-mission" ], "status": "", "generated": null, "verified": [], "stale_after": "", "sources": [], "body": "# The SEO Cliff and Recovery\n\nAround **May 22-24 2026** the elks.club fleet fell off a search cliff. Diagnosis\n(load-bearing): it was an **algorithmic scaled-content demotion**, NOT a manual\npenalty, a 521 outage, or a deindex. westmilford.biz, on the same infrastructure,\nheld steady as the control — so the cause was content, not hosting. Google\ndemoted a large set of similar, thin, auto-generated pages.\n\n## The lesson (now a platform rule)\n\nA flood of near-identical, thin sites is a liability, not growth. Every generation\nand growth decision inherits this:\n\n- **Enrich then index.** On-demand builds (see [network growth](../systems/network-growth.md))\n ship as a skeleton that is **`noindex` until it is enriched AND passes a quality\n gate**, then flips to index + sitemap. Never dump bare skeletons into the index.\n- **Variety and voice.** Thin sites are fixed with BETTER DATA and real\n [enrichment](../systems/location-data-enrichment.md), not tone. The\n [Muse system](../systems/muse-system.md) + families exist so sites don't read as\n templated slop.\n- **Quality gate has teeth.** [Regeneration](../systems/regeneration.md) is\n quality-gated with rollback; the \"More places nearby\" build bar keeps genuinely\n thin places out.\n- **Dedup + accuracy.** [Fact-Guard](../systems/fact-guard.md) and canonical\n handling keep pages distinct and correct.\n\nRecovery is content quality + dedup + a quality-gated index, not a hosting fix.\nThis is why \"make it work fast\" is always balanced against \"no slop, no dead ends\"\n([the mission](the-mission.md)) — the cliff is the proof of what happens when it\nisn't." }, { "id": "the-value-model", "title": "The Value Model (how Doozer creates and captures value)", "type": "Decision", "group": "decisions", "description": "Where Doozer's value comes from and how it is captured, so an AI understands the economic engine, not just the software.", "tags": [ "value", "monetization", "economics", "strategy", "why" ], "path": "decisions/the-value-model.md", "links": [ "no-dark-patterns-ethos", "the-network", "the-flywheel", "lead-capture", "implicit-verification", "two-tier-model", "billing", "livemusictonight", "prospector" ], "status": "", "generated": null, "verified": [], "stale_after": "", "sources": [], "body": "# The Value Model\n\nDoozer's premise: **most small businesses have no good web presence, and the\nmarket has failed to give them one cheaply, quickly, and tastefully.** Doozer\ngenerates one automatically from data the business already generates (Google\nPlaces, reviews, photos, its own activity). The value is created before anyone\npays, and captured along several honest paths, never with\n[dark patterns](no-dark-patterns-ethos.md).\n\n## Value created (before any charge)\n\n- A real, useful, accurate single-page site exists at a memorable domain, often\n better than the business's outdated official site or its absence.\n- The business becomes discoverable across the [network](../systems/the-network.md):\n NearByMeNow, Clouds, vertical directories, search.\n- Visitors get a fast, trustworthy answer to \"is this place open / good / near me,\"\n which is the whole [ethos](../systems/the-flywheel.md).\n\n## Value captured (how money is made)\n\n1. **Lead generation** — the primary engine. Every call, message, and intent\n signal is [captured and routed](../systems/lead-capture.md) to the business\n through LeadBuilder. Qualified leads are the product a business will pay for\n because they map directly to revenue.\n2. **Ownership / Doozer+** — a business [claims its site](implicit-verification.md)\n for free and can upgrade to the paid [Doozer+ tier](two-tier-model.md): a\n bespoke full site, priced via [Stripe billing](../systems/billing.md).\n3. **Premium features** — analytics, custom branding, agency multi-site\n management, higher new-site caps.\n4. **Sponsorship / advertising** — tasteful, network-level placements\n (`renderDoozerSponsorBar()`), never spammy.\n5. **Affiliate / referral** — booking, ticketing, and commerce CTAs where they\n genuinely help the visitor (e.g. tickets on [live music](../systems/livemusictonight.md),\n vetted \"Shop Now\" links).\n\n## Why this compounds\n\nEach captured signal makes the next site cheaper to justify and better targeted\n(via [Prospector](../systems/prospector.md) and enrichment). Value capture funds\nvalue creation, which produces more signal. That is [the flywheel](../systems/the-flywheel.md);\nthis node is its economics. The north star is never extraction: a site must be\ntrusted, working, accurate, tasteful, useful, and good, with no dead ends and no\nslop, or it is not shipped." }, { "id": "writer-model-and-accuracy", "title": "The writer model is chosen on accuracy, not price", "type": "Decision", "group": "decisions", "description": "GPT-5.4 mini writes Doozer's business copy. Decided 2026-08-22 by an 11-niche counterbalanced bake-off in which the more expensive model fabricated a verifiable fact on a live page.", "tags": [ "ai", "models", "accuracy", "cost", "content-generation", "decision" ], "path": "decisions/writer-model-and-accuracy.md", "links": [ "fact-guard" ], "status": "", "generated": null, "verified": [], "stale_after": "", "sources": [], "body": "# The writer model is chosen on accuracy, not price\n\n**Decision:** `business_website` content generation runs on **`gpt-5.4-mini`**.\n\n## The test\n\nEleven real businesses, one per niche, each regenerated by both candidates against\nidentical source data. **Counterbalanced**: a regeneration feeds the previous copy back\ninto the prompt, so whichever model runs second sees the other's work. Five businesses\nsaw Sonnet first, six saw GPT first, cancelling the order effect. Every cost read\nper-call from `ai_generation_history`, never estimated from a price sheet.\n\n| | claude-sonnet-4-6 | gpt-5.4-mini |\n|---|---|---|\n| per site | $0.03400 | **$0.00748** |\n| **per 100 sites** | $3.40 | **$0.75** |\n| seconds | 28.7 | **6.5** |\n| output tokens | 1,335 | 973 |\n\nCheaper and faster on **every single business**, low variance in both arms.\n\n## What actually decided it\n\nCost did not. $2.65 per hundred sites does not justify changing the voice of the network.\n\nWriting for **Thessen Services**, a plumber with no website on file and no cached source,\nSonnet opened: *\"Permit files across three county offices carry the record.\"* The strings\n`permit` and `county` appear **zero times** in that business's entire stored record. The\nsentence is fluent, specific, checkable, and invented. Given identical inputs,\ngpt-5.4-mini opened with the verified street address, and across all eleven specimens it\nstayed inside known facts.\n\n**A wrong fact is worse than a missing one.** That is the platform's whole premise for\n[fact-guard](../systems/fact-guard.md) and the geo-anchor rule, and it settled a decision\nthe cost data alone would not have.\n\n## Honest limits\n\nOne observed fabrication in eleven pairs is not a measured hallucination rate. It was\nenough to act on because the failure mode is severe and the cheaper model carried no\noffsetting cost, not because eleven samples prove a rate.\n\n**What we gave up:** Sonnet writes better headlines and ~27% more copy. A split where the\ncheap model writes the body and a stronger one writes the headline is worth testing.\n\n## How to re-run this\n\n`dz aimodelreg repoint=business_website model= live=1` swaps the writer;\n`dz aimodelreg sync=1 live=1` refreshes the priced catalog. **Before switching to any\nmore verbose model, check its output length against the pipeline's max-tokens cap** —\nSonnet 5 blew past 2,048 tokens, the JSON truncated, and it silently blanked two live\npages before `_regenContentIsSubstantive()` existed to catch it.\n\nCase study (all 22 generations readable side by side):\nhttps://claude.ai/code/artifact/a9ac8ae5-3bc9-477f-b731-b99950afe488\n\nRelated: [[magellan-and-feeds]], [[the-doozer-score]], [[fact-guard]]." }, { "id": "ai-discoverability", "title": "AI Discoverability — being the local layer AI agents cite", "type": "System", "group": "systems", "description": "How Doozer makes itself legible to AI agents and AI-powered search (ChatGPT, Perplexity, Claude, Gemini, Copilot, DuckDuckGo). The DDG=Bing insight, the explicit crawler welcome, llms.txt, and the machine-readable stack (schema.org JSON-LD + Atlas + design.md) that already existed.", "tags": [ "ai", "seo", "discoverability", "llms-txt", "robots", "duckduckgo", "bing", "indexnow", "atlas", "agents" ], "path": "systems/ai-discoverability.md", "links": [], "status": "", "generated": null, "verified": [], "stale_after": "", "sources": [], "body": "# AI Discoverability — being the local layer AI agents cite\n\nThe [[the-observed-world]] endgame is that AI agents are the new observers: they ask \"is there a\ngood X near me?\" and Doozer should always be able to answer \"yes, here it is, with structured\ndata.\" This node is how a Doozer host makes itself legible to AI and AI-powered search.\n\n## The load-bearing insight: DuckDuckGo is Bing\n\nDuckDuckGo does **not** run its own web index. Its results are overwhelmingly **Bing-sourced**\n(plus DuckDuckBot for a little, Apple Maps for local). So \"optimize for DuckDuckGo\" mostly means\n\"be in Bing\" — which the existing **[[indexnow]]** pipe already does (instant Bing submission on\npublish; verified healthy, HTTP 202s flowing). Same logic extends to the AI assistants: ChatGPT\nsearch, Copilot, and DuckAssist all lean on Bing's index. **IndexNow is therefore the single\nbiggest AI-search lever, and it was already built.** The gap was the AI-native layer below.\n\n## The machine-readable stack (most of it pre-existed)\n\nEvery Doozer business page already emits, and now advertises, structured data:\n- **schema.org LocalBusiness JSON-LD** (`schema-org.php`) — type-specific\n (FastFoodRestaurant, PostalAddress, GeoCoordinates, AggregateRating, opening hours). The single\n richest signal for both rich results and AI extraction.\n- **The [[atlas]] feed** at `/.well-known/doozer-atlas` (JSON) — the per-entity outward emission,\n linked in `` via ``.\n- **`/design.md`** (Google-Labs DESIGN.md) — agent-facing brand spec, `` in head, `X-Robots-Tag: noindex`.\n- **Sitemaps** + robots.txt served dynamically per domain.\n\n## What v2.2.420 added\n\n- **`/llms.txt`** (`includes/llms-txt.php`, the llmstxt.org convention) — a concise Markdown card\n served per domain that hands an agent a plain-language \"here's what this is\" plus links to all of\n the above. Four shapes: `master` (the network), `nbmn` (the directory), `root` (a directory root\n like elks.club/westmilford.biz — `isRootWildcardDomain()`, reads its `root_domains` name/tagline/\n description), and `business` (pulls real name/niche/city from `domains`→`businesses`, generic\n fallback if unresolved). Routed in `index.php` next to robots/design.md, in the sessionless +\n drain-skip fast paths. **Gotcha caught v2.2.421:** roots front many businesses, so they must NOT\n fall through the `business` branch (it would mislabel a whole directory as one local business).\n- **Explicit AI-crawler welcome in robots.txt** — `doozerAiCrawlers()` (GPTBot, OAI-SearchBot,\n ChatGPT-User, ClaudeBot, Claude-SearchBot, PerplexityBot, Google-Extended, Applebot, Bingbot,\n DuckDuckBot, DuckAssistBot, Amazonbot, Meta-ExternalAgent, CCBot, …). `User-agent: *` already\n allowed them; naming them is an intentional \"yes, index us\" (most of the web blocks these).\n Emitted only on business + NBMN (no Disallows to bypass); the master keeps `*` authoritative so\n its admin Disallows bind every bot, and just advertises the llms.txt summary line.\n\n## The stance (a choice, not a default)\n\nMost sites are racing to **block** AI crawlers. Doozer does the opposite: the whole model is that\nevery observed business should be findable, and being the structured local layer AI agents cite and\nroute through may be a bigger business than the sites themselves ([[the-observed-world]]). So we\nroll out the welcome mat and hand agents citable data. Guardrail: the data must be **true and\ncurrent** before we invite citation — the quality gate ([[the-mission]]) still governs what gets\nindexed and enriched; we never advertise a thin skeleton.\n\n## Verify by looking (not the token)\n`curl` the live surfaces on a real host: `/llms.txt`, `/robots.txt`, `/.well-known/doozer-atlas`,\nand grep the homepage for `application/ld+json`. Per [[feedback_verify_by_looking]], confirm on\nlive pixels/bytes, since a legacy path can silently no-op.\n\nRelated: [[indexnow]] (Bing pipe), [[atlas]] (outward emission), [[the-observed-world]] (agents as\nobservers), [[seo-cliff-recovery]] (only index what is real).\n\n## The brain itself, for agents (Sept 2026)\n\nThe whole knowledge bundle is live at four addresses on doozer.work, rendered from the\n`knowledge/` files on every request (15-minute cache), so deploying a node updates it:\n\n| form | address | robots |\n|---|---|---|\n| **HTML index, start here** | `https://doozer.work/brain.html` | none; ~30KB, one link per node |\n| HTML, one page per node | `https://doozer.work/brain/.html` | none; ~5 to 20KB each, cross-links rewritten, prev/next |\n| HTML, everything on one page | `https://doozer.work/brain-full.html` | none; ~420KB, for readers that can take it |\n| Markdown | `/brain` | noindex, noarchive (shareable, not a search result) |\n| plain text | `/brain.txt` | noindex |\n| JSON | `/brain.json` | noindex |\n\nThe HTML forms exist because most agent fetchers choke on `text/markdown`, on an\nextensionless URL, on a single 450KB document, or treat noindex as \"do not read\". The\nserver was never at fault (every form returned the right type); the SHAPE was. Give an\nagent the index and it can walk the pages it needs. The operator's rule: it is not\nopen source, and it is not the secret recipe; hand the `.html` address to an agent and\nit reads everything, with a table of contents." }, { "id": "ai-postcards", "title": "AI Postcards — Factory, Theme Studio, and Campaigns", "type": "System", "group": "systems", "description": "How Doozer builds and mails postcards. The Factory assembles accurate cards deterministically (real screenshot/code/QR, no per-card AI cost); the AI Theme Studio designs vision-gated backgrounds; campaigns give each card a purpose + audience. Claim Your Site is the first campaign.", "tags": [ "postcards", "factory", "theme-studio", "campaigns", "claim", "thanksio", "direct-mail", "vision-gate", "audience", "ai-image" ], "path": "systems/ai-postcards.md", "links": [], "status": "", "generated": null, "verified": [], "stale_after": "", "sources": [], "body": "# AI Postcards + the Postcard Factory\n\n> **v2.2.381 — the Factory is now the default, accurate path.** Generating the\n> whole card with AI every time was expensive AND inaccurate (it approximated the\n> claim code, invented the short URL, hallucinated the domain in the screenshot's\n> address bar). The **Postcard Factory** (`includes/postcard-factory.php`) flips\n> it: AI designs backgrounds/layouts; every ACTUAL card is composed\n> deterministically from REAL values and flattened to a print-ready 1800x1200 PNG\n> via **Cloudflare Browser Rendering** (`postcardFactoryFlatten` posts `html` +\n> viewport to the same CF endpoint used for screenshots). Real screenshot in a\n> browser chrome showing the ACTUAL Doozer domain, real minted claim code, real\n> doozer.link short URL, a real scannable QR, real logo, Machi copy. No per-card AI\n> cost, nothing to proofread. `postcardFactoryCompose($bizId,$opts)` files it in\n> the same review queue (no gate — values are deterministic). Themes: paper / navy.\n> Admin: AI Postcards page \"Build card\" panel; Machi defaults to engine='factory'.\n\n> **v2.2.395 — Multi-campaign system.** Postcards are no longer claim-only. A\n> **campaign** = purpose + audience + copy/offer (`postcard_campaigns`,\n> `includes/postcard-campaigns.php`). The seeded, locked **claim_your_site**\n> campaign (audience=unclaimed) IS the old behavior, now named. `campaign` already\n> threaded through postcard_designs/thanksio_sends/claim_codes/machi_touches as a\n> string; this formalizes the keys. **Audiences** (hard-coded): all / unclaimed\n> (admin_email empty) / claimed (admin_email set) / premium (owner lb_user on a\n> premium-class tier), each + niche (primary_niche) + location (state_code/city);\n> base = live Doozer site + mailable address. `postcardCampaignAudienceWhere/Count/\n> Sample`. **Purpose seeds generation:** `postcardCampaignThemePromptSeed` feeds the\n> Theme Studio background prompt (`postcardThemeCreate` opt `campaign`);\n> `postcardCampaignMessage` resolves the BACK copy (claim → warm/leads/curious\n> variants; else message_template with tokens {name}{city}{code}{offer_code}\n> {short_url}). Admin: Campaigns cards + Create/Edit modal (live audience count),\n> Campaign selector on Factory + Studio, review queue pagination + finder (search +\n> campaign filter). `dz campaign do=list|show|save`. NEXT phase: campaign-specific\n> FRONT copy + audience-gated sending (don't mail a claimed business a claim card).\n\n> **v2.2.392 — Two-score gate + back copy + Thanks.io levers.** The theme gate\n> (`postcardThemeGateCard`) now returns TWO independent real scores because there is\n> no in-admin way to tweak a theme after the fact: **accuracy** (every required\n> element present, uncropped, legible — an explicit checklist is passed to the vision\n> model) and **design** (aesthetics + theme match only). A theme goes ACTIVE only\n> when BOTH clear `postcard_theme.gate_pass_score` (default 78); else `draft`. Stored\n> in `postcard_themes.design_score` / `accuracy_score` (idempotent ALTER); shown in\n> the Studio result and gallery tiles. Card template fix: `.left` scrim is full grid\n> height (`grid-template-rows:100%`) so the \"doozer.\" wordmark is always inside the\n> legibility box. **Back-of-card copy** (`thanksIoClaimMessageVariants` in\n> `thanksio.php`): warm / leads / curious variants, personalized with the town + a\n> typed `doozer.link` fallback, no em-dashes. **Thanks.io best practice:** the FRONT\n> is the Factory image; the BACK is `message` + `qrcode_url` + return address. Turn\n> on `thanksio.handwriting_style_id` (handwritten back lifts response), set\n> `thanksio.size` (4x6 default; 6x9/6x11 stand out but need a matching front aspect),\n> `thanksio.message_variant`. Rules that win direct mail: personal, specific to them,\n> ONE clear action (scan), readable in three seconds, honest, warmly signed.\n\n> **v2.2.390 — AI Theme Studio.** The untrustworthy full-AI card painter is\n> repurposed into a theme/background designer only; the Factory still does the real\n> assembly. `includes/postcard-theme-ai.php`: `postcardThemeCreate($style,$opts)`\n> takes a plain-words style (\"beach vacation\", \"Thanksgiving warm orange\",\n> \"Bronx blue/white pinstripe\") + optional `business_id`/`match_site` for niche\n> style cues, builds a LAYOUT-AWARE background prompt (calm left third for text,\n> calm bottom-right ~1.5in for QR, right half supporting the screenshot, NO\n> text/letters/logos), generates the bg via the configured image provider\n> (`postcardAiImageProvider`), then a **vision pass reads the palette BACK from the\n> pixels** (`postcardThemeReviewBg` → accent/ink/dark, reads `raw_text`). It then\n> composes a REAL sample card (live screenshot + demo code/QR) and runs a second\n> **vision gate** (`postcardThemeGateCard`) for legibility/layout/design; score\n> >= `postcard_theme.gate_pass_score` (default 78) saves `status=active`, else\n> `draft`. Themes are data in **`postcard_themes`** (theme_key, source\n> seed/ai/operator, style_prompt, bg_type color|image, bg_value, accent/ink/dark,\n> status, gate_score/reasons, preview_url); `postcardFactoryThemes()` merges seeds\n> (paper/navy/kraft) + active DB rows so a passing theme is instantly pickable in\n> the Factory. Image backgrounds get an auto legibility scrim behind the left text\n> column (`postcardFactoryHtml` `$bgIsImage`). `postcardFactoryHtml(...,$themeSpec)`\n> takes a candidate spec so the Studio can preview before saving.\n> Dev API: `dz factorytheme do=create style=\"...\" [b=] [match=1]`,\n> `do=status key= set=active|rejected`, `do=list`. Admin: AI Postcards page has the\n> AI Theme Studio card (style + business picker + match-site) and a theme gallery\n> (activate/retire). The AI Postcards business picker uses the same\n> `admin_business_search` autocomplete and its dropdown is opaque. First run:\n> \"beach vacation\" scored 92, shipped a genuinely good card (\"Tropical Escape\").\n> `dz factory compose b= [theme=] [angle=]`. The old full-AI painter (below) is the\n> fallback (engine='ai'), kept for background-art experiments.\n>\n> **Themes (v2.2.382):** paper (light editorial), navy (bold dark), kraft (warm\n> local). Theme colors derive from a `dark` flag + optional panel/muted/chrome\n> overrides — adding a theme is a few lines in `postcardFactoryThemes()`. Layout:\n> local eyebrow + headline that **auto-sizes to its length** (any Machi angle fits\n> the fixed 6x4 card) + screenshot as a real `` in a `overflow:hidden` crop\n> box (full nav, no white gap) inside browser chrome showing the real domain.\n> Render notes: QR inlined as a data URI (external QR service timed out the\n> browser); `networkidle2` + paint delay; 429 backoff-retry.\n>\n> **Load-bearing bugfix shipped here:** `claimCodeCreate()` validated the DEFAULTED\n> intent but assigned the RAW `$opts['intent']`, so any caller not passing intent\n> (every postcard) failed with \"Column 'intent' cannot be null\" and got no code.\n> The AI cards hid it by inventing a code; the Factory surfaced it. Real codes now\n> mint network-wide.\n\n## Sent & performance tracking + independent resend (v2.2.407)\n\nEvery send already mints its OWN claim code + doozer.link shortlink + Thanks.io\n`order_id`, so each touch is independently trackable — the schema never limited a\nbusiness to one card. The admin Sent section (v2.2.409) is bounded so it never runs\nwild at scale: three **last-5 glances** (Sent / Delivered / Touched = scan·visit·claim)\nplus a full **All sends** table with search (business/code), campaign + status\n(delivered/scanned/claimed) filters, sort-by-date, pagination, and a **Doozer+ column**\n= full conversion (claimed + owner on a premium tier).\n\n- **`postcardDesignLiveStats(array $design)`** (`postcard-ai.php`) reads outcomes LIVE\n from `thanksio_sends` (cost/order/preview), `thanksio_events` (delivered + QR scans),\n `shortlinks.click_count` (visits), `claim_codes.redeemed_at` (claimed). Never the cached\n JSON. `postcardAiTracking()` delegates to it + caches. The old code queried a\n non-existent `shortlinks.visits` column (always 0) — fixed to `click_count`.\n- **Webhook** (`thanksIoHandleWebhook`) recomputes the linked design's tracking on every\n delivered/scan event, so the view stays fresh without a manual Refresh.\n- **Resend:** `?ajax=resend` on `admin-postcards-ai.php` re-runs `postcardFactoryCompose()`\n for the same business + campaign + theme (theme recovered from `model` = `factory:`)\n → a NEW `pending_review` card with a fresh code. Never auto-mails; operator Previews /\n Sends Real. Delivered/scan status fills in as Thanks.io reports it (minutes→days).\n- **View front + back (v2.2.410):** each send's \"View\" button opens a lightbox with the\n Factory front + the real Thanks.io handwriting back. Proofs persist to\n `postcard_designs.proof_urls` on preview/send; `?ajax=proof` fetches them free on demand\n for older sends (a preview of a `sent` card is allowed — free, no mail) and caches. NOTE:\n Thanks.io previews live at `response.data.previews` (front + handwriting back, S3 URLs).\n- **Cost bug FIXED (v2.2.409):** Thanks.io returns `authorization_total`/`leads_fee` ALREADY\n in cents (114 = $1.14 for a 4x6, 1 recipient); the send path was multiplying by 100 again.\n Dropped the `*100` (thanksio.php ~357); `dz postcard do=fixcosts` re-derives historical rows\n from raw meta.\n- **No stray logo (v2.2.414):** the Factory top-right \"logo\" was `businesses.logo_url`, an\n unreliable scrape (often a site PHOTO, not a logo). Slot removed (`$logoBlock=''`); the\n screenshot already shows real branding. Re-enable only behind a trustworthy is-a-logo signal.\n- **Size is a variable (v2.2.414):** 4x6 and 6x9 share the SAME 2:3 art (1800×1200), so no\n re-render — pick per send via the review-card selector (4x6/6x9/6x11). Plumbs postcardAiSend\n → thanksIoMailClaim → Thanks.io; recorded on `thanksio_sends.size`.\n- **Format science (v2.2.414):** `postcardFormatPerformance($niche,$state,$days)` + a \"Format\n performance\" admin panel — funnel (sent→delivered→scanned→claimed→Doozer+ converted) by SIZE\n as a rate of sent, sliceable by niche/state/timeframe, with cost/claim + a thin-sample flag\n (n<30). Claim rate is the money metric.\n\n## Roadmap (the Marketing Engine this seeds)\n\n- **Phase 2 — Internal LeadBuilder / \"Doozer awareness\" CRM:** businesses are OUR\n prospects; every touch (postcard sent/delivered/scanned/claimed, site created, leads we\n deliver to them) rolls into a per-business awareness score → internal Hot Leads to convert\n free→Doozer+→Keeper→agency. Reconcile with [[machi]] rather than duplicate.\n- **Phase 3 — BYO-key thanks.io reseller Marketing Engine:** Doozer+ businesses send\n direct-mail + AI marketing to their OWN leads. Needs a `getApiKeyForBusiness()` seam off\n the single `getApiKey()` chokepoint, per-business thanks.io key, owner send tool on\n `manage-business.php`, a 50% affiliate revenue ledger, agency/franchise tiers. Reuses the\n Factory + the two-score `/frontend-design` vision gate already built.\n\n---\n\n# AI Postcards — fully-generated claim mail with a quality gate (fallback painter)\n\n**What:** The physical arm of the observed-world flywheel. When a business has no\nemail on file (unclaimable via implicit verification), we mail a real postcard\ncarrying the site's own screenshot, a claim code, and a scannable QR. The card\nDESIGN is AI-generated end to end and passes a vision-model quality/accuracy gate\nbefore any human sees it. No templated fallback — if the AI can't produce a good\ncard in 3 tries, it fails loudly for review instead of mailing slop.\n\n**Engine — `includes/postcard-ai.php`**\n- `postcardAiGather($businessId)` — assembles real ingredients: live site\n screenshot (`siteScreenshotUrlForHost`, Cloudflare Browser Rendering -> Spaces),\n a minted claim code + doozer.link QR (`claimCodeCreate`), business facts, logo.\n- `postcardAiBuildPrompt($ctx)` — detailed 6x4 postcard art-direction prompt:\n use the provided screenshot faithfully as the browser-framed hero, exact\n business name / claim code / URL, reserve a QR square, Doozer green.\n- `postcardAiGenerate($prompt,$refImageUrls)` — Gemini `generateContent` with the\n screenshot + logo passed as real `inlineData` image inputs (Gemini is the only\n configured engine that accepts image inputs). Needs an image-capable Gemini key\n in `api_keys` (service `gemini`/`google`/`google_gemini`).\n- `postcardAiGate($imageUrl,$ctx)` — SCANS the generated image with a vision model\n (`callVisionProvider` openai/anthropic), returns JSON `{suitable,score,reasons}`.\n Pass threshold = `platform_settings` `postcard_ai.gate_pass_score` (default 75).\n- `postcardAiRun($businessId,$opts)` — orchestrates gather -> up to 3\n generate/save/gate attempts. Suitable design -> `pending_review`; three failures\n -> `failed` with all three attempts + reasons kept.\n- `postcardAiSend($designId,$opts)` — mails via `thanksIoMailClaim` (front_image_url\n = the generated card). `live` flag gates preview vs real mail (costs money).\n- `postcardAiTracking($designId)` — rolls up Thanks.io scan events + doozer.link\n shortlink visits + claim-code redemption.\n\n**Table:** `postcard_designs` (business_id, claim_code_id, screenshot_url, logo_url,\nqr_url, redeem_url, prompt, image_url, model, attempts, gate_score, gate_verdict,\ngate_reasons, status ENUM('generating','pending_review','failed','approved','sent',\n'rejected'), failures JSON, thanksio_send_id, sent_at, tracking JSON).\n\n**Admin — `includes/admin-postcards-ai.php`** (Admin -> Infrastructure -> AI\nPostcards, route `postcards-ai`). Human-in-the-loop: ready designs show the card +\ngate score with a Send button (live checkbox); sent designs show live tracking;\nfailed designs show 3 attempts + Retry. Generation runs as a background\n`postcard_ai` job (dispatcher case), so the screen never blocks.\n\n**Dev API:** `dz postcard gen b=` (queue+run), `list`, `show id=`, `send id=\n[live=1]`, `retry id=`, `track id=`.\n\n**The claim loop:** sending sets `sent` and starts the state machine; a QR scan or\ncode redemption sets the owner's `businesses.admin_email` — the postcard IS proof\nof claim (implicit verification, no claims table). See [[claim-codes]],\n[[thanksio]], [[the-observed-world]].\n\n**State:** shipped v2.2.379 (Jul 7 2026). Blocker for first real run: an\nimage-capable Gemini key must be in `api_keys`; vision gate keys (openai/anthropic)\nalready present. First target = Powell Flooring (business id 1, West Milford NJ,\nemail NULL, screenshot already captured to Spaces)." }, { "id": "best-ai-for-the-job", "title": "Best AI for the Job — value-aware model selection", "type": "System", "group": "systems", "description": "How Doozer decides which AI model to use for each function, when, why, and for what — balancing quality against cost by the value of the work, learning from its own scores, and staying provider-diverse on purpose.", "tags": [ "ai", "models", "cost", "quality", "scoring", "strategy", "doctrine" ], "path": "systems/best-ai-for-the-job.md", "links": [ "site-scoring" ], "status": "", "generated": null, "verified": [], "stale_after": "", "sources": [], "body": "# Best AI for the Job\n\nDoozer does not use one model for everything, and it does not chase the cheapest\nmodel. It uses **the best model for each job** — chosen intelligently, weighed by\nthe **value of the work against its cost**, and refined by what the work actually\nscored. \"The best man for the job\", made mechanical.\n\n## THE GOAL\n\n> Build **Solid A** rated sites — accurate, beautiful, tasteful, helpful,\n> valuable, useful — for **every business that should have one**. Par-create\n> decides who should have one. The scoring of what we build drives the resources\n> spent on the next build. The fleet average climbs generation over generation.\n\nSolid A = weighted **≥ 85** across the [six goals](site-scoring.md)\n(`dzQualityGoal()`, tunable `platform_settings.doozer_quality_goal`). This is not\na per-site retry loop — we build sites one after another, each using the current\nbest-known strategy, and the results steer the next build. When a choice raises a\nniche's average we keep it; **when a choice regresses it, we undo that choice and\ntry another until the score climbs.** Doozer builds because — and it gets better\nevery generation, toward leading-edge, lead-generating sites at scale.\n\n### The self-improving ratchet (`quality-autopilot.php`)\n\nThe unit of improvement is the **niche** — sites within a niche score alike, so a\nstrategy that lifts one lifts them all. Each niche holds a `niche_build_policy`\n(the current strategy: model tier, deep-facts on/off, the baseline it's beating).\n`qualityRatchetTick()` (`dz goal autopilot=1 go=1`):\n\n1. A niche **below the goal** and un-escalated → escalate its next builds (GO HARD\n + deep source-of-truth). Record the baseline to beat.\n2. An **escalated** niche → compare its fresh average to the baseline:\n improved → **commit** (new baseline, keep climbing); regressed → **revert** the\n choice and mark that lever \"tried, didn't help\" so the next pass reaches for a\n different one; flat → hold, gather more data.\n3. **At/above goal** → leave the value-aware default (don't overspend).\n\nThe router reads the niche policy (`aiForJob($job, ['niche'=>...])`) and escalates\naccordingly. `dz goal` reports fleet average, at-goal count, and per-niche standing\nworst-first — the niches the ratchet is working on.\n\n**First reading (July 2026):** fleet 80.3, goal 85, 12/46 at goal. Weakest niche:\n**restaurant (74, accuracy 67)** — high fact density (menus/prices/specials) is\nwhere content invents things. Escalated. Real-estate (84/acc 88) and non-profits\n(84) are already near goal. The single biggest accuracy lever is reading the real\nwebsite: prefer the **free Jina source-of-truth cache** over the paid, deprecated\nFirecrawl `deep_research` (v0 API) — same job, better accuracy, no cost. Retiring\nFirecrawl for enrichment is the recommended consolidation.\n\n\nThis is doctrine, not a setting. It encodes how much care goes into a Doozer\nsite: the accuracy, the taste, the scoring, the deliberate balance of cost and\nquality — and the deliberate refusal to become dependent on any one AI house.\nDoozer builds because. It does not waste time, and it does not waste money — but\nit never trades away real value to save pennies.\n\nCode: `includes/ai-job-router.php` (the engine), `includes/ai-models.php` (the\nmodel catalog + tiers + cost map), `includes/site-scoring.php` (the feedback).\nOperator surface: `dz aimodels`, `dz aimodels pool=1`.\n\n## The principle (Jon's words)\n\n> \"There is no reason to use a cheap model for even a slight loss in quality if\n> the value is still hundreds of times the cost.\"\n\nSo the question is never \"what is cheapest.\" It is: **is the quality I would give\nup by going cheaper worth more than the money I would save?** If yes, GO HARD.\n\n## Three tiers, one framing\n\n| Tier | Framing | Anthropic | OpenAI | xAI | Google |\n|---|---|---|---|---|---|\n| flagship | **GO HARD** | Opus 4.8 | GPT-5 | Grok 4 | Gemini 2.5 Pro |\n| balanced | **Solid A** | Sonnet 5 | GPT-5 mini | Grok 4 Fast | Gemini 2.5 Flash |\n| budget | **Economy** | Haiku 4.5 | GPT-5 nano | Grok 3 mini | Gemini Flash-Lite |\n\nThe tier resolves to the **current best model in that class** via\n`aiModelResolve()` — so when a new model ships, we update the catalog in one place\nand every job that asked for a class is upgraded. Pin a concrete id only to freeze\na chore to a known model.\n\n## The math (the sweet spot, per output)\n\nEvery AI function declares four things (`aiJobRegistry()`):\n\n- **floor** — the lowest tier it may ever use (a quality floor).\n- **value** — the dollars one *good* output is worth.\n- **spread** — how much output quality *actually* varies flagship→budget for this\n job. A label is a label (spread ≈ 0.02: a cheap model nails it). Bespoke site\n copy is not (spread ≈ 0.15: the creative gap is real and worth paying for).\n Difficulty, not just value, decides.\n- **typical tokens** — for the cost estimate.\n\nThe engine walks candidates best-quality-first (flagship → floor) and steps down\nto a cheaper model **only when**:\n\n```\nΔquality × value ≤ Δcost\n```\n\nThe dollar value of the quality you'd lose vs the dollars you'd save. It stops at\nthe first step where quality is worth more than the savings — that is the sweet\nspot. For a high-value output (a site that is a claimable lead), the pennies of\ncost delta never outweigh the quality, so it **goes hard**. For instrumentation\n(scoring) or trivia (classification), the cheap model is genuinely good enough.\n\nQuality per tier starts from a difficulty-aware prior\n(`1 − spread × tierPenalty`, penalty: flagship 0, balanced 0.5, budget 1.0) and is\nthen **blended toward measured evidence** as real scores accumulate.\n\n## What the engine currently decides\n\n- **GO HARD (Opus 4.8)** — content, content_flagship (hero/visitor builds),\n design/Muse, strategy, oracle, enrichment, marketing, conversation, vision.\n These touch the customer or feed accuracy; their quality is worth far more than\n the cost delta.\n- **Solid A (Sonnet 5)** — scoring. It is internal instrumentation: quality-\n insensitive and high-volume, so Solid A is the sweet spot.\n- **Economy (Haiku 4.5)** — summary, extraction, classification. Trivial, high-\n volume; a cheap model is as good, and at volume the cost is what matters.\n\nSee it live: `dz aimodels` prints job → choice → model → value → est cost → why.\n\n## The learning loop (it gets smarter)\n\nPriors are a starting belief, not the last word. Every scored site feeds\n`aiRecordJobQuality(job, provider, model, score)` into `ai_model_quality`, so the\nengine learns the **real** quality each model produces for each job — the score\nfrom one model vs another, over real Doozer sites. Content generation records\nwhich model wrote a site (`businesses.custom_settings.content_model`); when the\n[six-goal scorer](site-scoring.md) rates that site, the score is credited to the\nmodel that wrote it. Over time the decision sharpens from evidence, not assumption.\n\n## Diversity — never platform-dependent\n\nA small share of eligible calls (≈10%) is routed to an **alternate provider of the\nsame tier**. This is deliberate: it keeps quality estimates fresh across houses,\nkeeps every vendor warm and callable, and means Doozer is never hostage to one\nAI company's pricing, availability, or policy. If one house stumbles, the work\nkeeps flowing. Diversity is resilience, and it is also honesty about the fact that\ndifferent models genuinely produce different results for the same prompt.\n\n## Overrides (they win)\n\nThe algorithm is the default, not a cage. Per call: `['hard' => true]` forces\nflagship, `['tier' => ...]` / `['provider' => ...]` pin a choice. Per job:\n`platform_settings.ai_job_tier.` and `ai_job_provider.`\n(`dz aimodels set job= tier= provider=

`). Only **callable** models\n(API key present) are ever chosen, so it just works as keys come and go.\n\n## Provider notes / gotchas\n\n- **Thinking-capable models** (Sonnet 5; adaptive-thinking Opus) return a\n `thinking` content block *first* — code must scan `content[]` for the text block,\n never assume `content[0]`. Both `callAnthropic` and `generateWithClaude` do.\n- **OpenAI GPT-5 / o-series are reasoning models** — they spend a large, invisible\n share of the completion budget on reasoning before the answer, so JSON/structured\n tasks need generous `max_completion_tokens` (the router path adds headroom).\n- **Google Gemini** routes via its OpenAI-compatible endpoint; needs a `google`\n api_keys row to be callable.\n\n## Still to wire (follow-ups)\n\n- The flexible content path (`generateContentFlexible`) should set\n `__lastContentModel` too, so the learning loop captures every content route, not\n just `generateWithClaude`.\n- Migrate the remaining hard-pinned call sites to `aiForJob()`:\n `muse-family-generator`, `muse-recompute-palette`, `ai-classifier`,\n `anthropic-chat`.\n- A per-job monthly budget governor for very high-volume jobs.\n\n## Why this matters\n\nA Doozer site is built with care: real source material read and fact-checked, six\ngoals measured, taste enforced. The model behind that work is chosen with the same\ncare — the best tool for each job, paid for when the value is there, saved when it\nis not, learned from what it produced, and never locked to one vendor. That is how\nwe create value without wasting time or money." }, { "id": "billing", "title": "Billing", "type": "System", "group": "systems", "description": "Product-agnostic Stripe billing — one connection sells everything, entitlements flow to lb_users.tier.", "tags": [ "billing", "stripe", "monetization" ], "path": "systems/billing.md", "links": [ "site-creation" ], "status": "", "generated": null, "verified": [], "stale_after": "", "sources": [], "body": "# Billing\n\nOne Stripe connection sells everything (Premium now; add-ons, domain-connect later).\n`includes/billing.php` is the product-agnostic core.\n\n- `billing_products` (SKU catalog; kind sub|one_time; `grants` entitlement; per-mode\n price ids), `billing_orders` (ledger), `billing_subscriptions`.\n- Secrets are ENCRYPTED in `platform_settings` (not `api_keys`, not env). No SDK —\n a curl client. Checkout for both kinds; HMAC webhook to `billingGrantEntitlement()`\n (the same grant path as founders codes).\n- Entitlement = `lb_users.tier`. Cancel only downgrades `premium_source='stripe'`.\n- Cost protection: clouds (directories over existing sites) are unlimited; creating\n BRAND-NEW sites is metered per user per month (`user_site_creations` +\n `platform_settings billing.limit_new_sites_pm`). See [site creation](../processes/site-creation.md).\n- Self-serve via Stripe Customer Portal (`billingCreatePortalSession()`).\n\nAdmin: the Revenue nav group (`admin-billing.php` + `admin-users.php`). Adding a product\nis a Stripe Price + a catalog row, no new plumbing." }, { "id": "cloud-headers", "title": "Cloud Header Images", "type": "System", "group": "systems", "description": "Every cloud (and root) gets a header. Real image > Keeper opt-out gradient > a designed per-cloud placeholder. AI generation is the upgrade path.", "tags": [ "clouds", "design", "images", "ai" ], "path": "systems/cloud-headers.md", "links": [ "cloud", "index" ], "status": "", "generated": null, "verified": [], "stale_after": "", "sources": [], "body": "# Cloud Header Images\n\nA [Cloud](../glossary/cloud.md) should never read as blank just because its Keeper has\nnot yet uploaded or generated a header. As of v2.2.197 every cloud has a header by\ndefault. Engine: `includes/cloud-header-ai.php`.\n\n## Precedence (`cloudHeaderTopCss($img,$src,$name,$c1,$c2)`)\n\n1. **Real image** (`header_image_url` set) → the image with a gentle legibility overlay.\n2. **Keeper opt-out** (`header_image_source = 'none'`) → a plain brand-color gradient.\n This is a deliberate manual choice (a \"No header image\" checkbox in the cloud editor),\n never the default.\n3. **Otherwise** → a designed, per-cloud **placeholder** (the default).\n\n## The placeholder (free, instant, distinct)\n\n`cloudHeaderPlaceholderSvg($name,$c1,$c2)` builds an SVG from the cloud's own brand colors:\na diagonal gradient, a soft light bloom, a seeded ring motif (deterministic per cloud via\n`crc32(name)` so each differs), and a faint serif monogram of the cloud's first letter.\nServed as a data URI (`cloudHeaderPlaceholderDataUri()`), so it costs nothing and renders\nimmediately. Used on the [Discover Clouds](../index.md) cards (`includes/discover-clouds.php`).\n\n## AI headers (the upgrade)\n\n`cloudGenerateHeader($cloudId,$provider)` composes a header from the cloud's vibe (type,\nniches, place, colors), never a literal image, via GPT Image or Gemini Nano Banana 2\n(v2.2.11). Per-cloud \"Generate AI header\" lives in the cloud editor; a batch\n\"Generate missing headers\" (Admin → Clouds) backfills clouds with none, capped per run\nbecause each call costs an image credit (operator-triggered, respecting\n[API-cost discipline](../index.md)). The placeholder fills the gap until an AI or uploaded\nimage lands.\n\nDecision: headers are on by default (placeholder), opting out is manual, real images are\nthe goal. Taste first, no blanks, no surprise spend.\n\n## The flowing-cloud movement engine (v2.2.516)\n\nDistinct from the header IMAGE above: the animated cloud LAYER over the hero\ngradient. `includes/cloud-texture.php` → `cloudTextureLayer()` (drop-in on\ncloud-directory, discover-clouds, cloud-create, me-cloud). A WebGL fragment\nshader — fractal noise (fbm) + domain warping, animated by time — so the clouds\ngenuinely FLOW and morph (not a panning texture). Inspired by OpenAI's GPT-Live\nhero backdrop, rebuilt from scratch.\n\nEvery look is a uniform, driven from the my.doozer.cloud vibe controls:\n- **Mood** (`--c1/--c2`) → cloud colour; call `window.dzClouds.refreshPalette()`.\n- **Energy** (0..4) → `window.dzClouds.setEnergy(n)` (speed + vividness).\n- **Storm** (new slider, Clear→Tempest) → `window.dzClouds.set({storm})` ramps\n warp amplitude, turbulence, speed, and contrast.\n- Also `set({speed,vivid,tintAmt})`; all persist to localStorage.\n\nResponsible: DPR capped 1.75, `low-power`, paused when the tab is hidden or the\nheader is off-screen (IntersectionObserver). Graceful fallback: no WebGL or\n`prefers-reduced-motion` → the original two-layer SVG fractalNoise texture\n(`cloudTextureSvgUri`), kept intact. Self-contained, no CDN." }, { "id": "clouds", "title": "Clouds (curated directories)", "type": "System", "group": "systems", "description": "The cloud engine — how niche/region/criteria directories are built, accessed, and personalized, including the Cloud Factory and my.doozer.cloud.", "tags": [ "clouds", "directory", "curation", "cloud-factory", "doozer-cloud" ], "path": "systems/clouds.md", "links": [ "cloud", "architecture", "directory-framework", "shared-business-card", "cloud-headers", "prospector", "the-flywheel" ], "status": "", "generated": null, "verified": [], "stale_after": "", "sources": [], "body": "# Clouds\n\nA [Cloud](../glossary/cloud.md) is a curated directory of businesses grouped by\nniche, region, or arbitrary criteria. Clouds sit on the same\n[engine](architecture.md) as roots and NBMN, rendered through the shared\n[multi-view framework](directory-framework.md) and [business card](shared-business-card.md).\n\n## The engine\n\n`includes/cloud-engine.php`. Clouds use `is_active` (NOT `status`). Membership is a\n**filter** (states / cities / geo bounds), not a fixed radius, so large areas work.\nManual curation can include/exclude specific businesses (admin Members panel).\n`doozer.cloud` apex is the public **Cloud of Clouds** (Discover Clouds). Each cloud\ncarries an AI-generated [vibe header](cloud-headers.md).\n\n## Access model\n\nPublic (AUTO or CLOSED join), Unlisted, or Private, so a cloud can be an open\nregional directory, a curated collection, or a members-only list.\n\n## Cloud Factory\n\n`includes/admin-cloud-factory.php` (Decide → Build → Manage): give it a niche +\nregion and it creates the cloud, runs a [Prospector](prospector.md) sweep, and\nbatch-builds the discovered businesses (which auto-join). Geo areas reuse\n`googleGeocodeSearch` bounds. This is how a themed directory goes from idea to\npopulated in one flow.\n\n## Personal — my.doozer.cloud\n\nEach signed-in user gets a personal cloud (`includes/cloud-directory.php` personal\nbranch) with a **Vibe System**: Mood (color) x Energy (0-4) preference; headlines\nfollow energy via `meCloudHeadlineBank()`; reduced-motion keeps colors. This is the\nconsumer-facing, \"your neighborhood, your way\" surface. Saved businesses derive\ntheir URL from the business's ACTIVE domain, never a stored `lb_follows.domain_id`.\n\nClouds turn the flat fleet into infinite meaningful cross-sections, each a new\ndiscovery surface feeding [the flywheel](the-flywheel.md)." }, { "id": "content-generation", "title": "Content Generation Pipeline (providers, models, timeouts)", "type": "System", "group": "systems", "description": "How AI site prose is actually produced — the two provider paths, model config, the 90s timeout, the anti-boilerplate footer, and every failure mode that bit us.", "tags": [ "ai", "content", "providers", "reliability", "seo" ], "path": "systems/content-generation.md", "links": [ "content-generation-and-heal", "location-data-enrichment", "design-standards", "dev-api", "hosting-infrastructure" ], "status": "", "generated": null, "verified": [], "stale_after": "", "sources": [], "body": "# Content Generation Pipeline\n\nThis is the engine behind [Content Generation and Healing](../processes/content-generation-and-heal.md).\nIt produces `businesses.ai_generated_content` (headline, about, services, why_choose_us, faq,\nmeta_description, suggested_colors). Hard-won operational truths live here — read before touching\nAI content, model config, or regeneration.\n\nThe governing principle (why site voice varies so much place to place) lives in\n[Per-Location Data Enrichment](location-data-enrichment.md): a site's voice is signal-in,\nsignal-out. The lever for a thin site is more/better input data, never a forced tone.\n\n## Entry point + the TWO paths (keep both in sync)\n\n`generateBusinessContent($businessRow)` in `includes/ai-content.php` is the entry. It takes the\n**business row** (from `getBusinessById()`), NOT a Google-Places shape. There is **no**\n`generateContent()` — calling that name silently broke every content regen with \"Content generator\nunavailable\" (fixed v2.2.235).\n\nIt tries two paths, and a change to ANY of prompt / timeout / model must cover BOTH:\n\n1. **Flexible path (tried FIRST, used in production):** `generateContentFlexible()` in\n `includes/ai-provider-system.php`. Reads the per-content-type model config, builds the prompt\n from the DB template, calls `callAnthropic()` / `callOpenAICompatible()`.\n2. **Legacy path (fallback):** `ai-content.php`'s own `callAnthropic`/`callOpenAI`. Has its own\n model resolution + the historical default `claude-3-5-sonnet-20241022`.\n\nDURABLE RULE: the flexible path is what runs ~always. If you only patch `ai-content.php` you patched\nthe wrong path. (This exact trap meant the anti-boilerplate footer didn't apply for a full cycle —\nsee below.)\n\n## Model config (settings, not code)\n\nPer-content-type provider/model lives in the **`ai_content_configs`** table (rows: `business_website`,\n`photo_vision`), joined to `ai_models` + `ai_providers`. Set it via **Admin → AI Management**\n(it's under the **Infrastructure** menu, `?page=admin§ion=ai` → Content Configuration → Configure),\nNOT a migration. Class aliases resolve via `aiModelResolve()` over the `includes/ai-models.php`\ncatalog.\n\nDURABLE RULE: the content **primary model must be a FAST quality model — `claude-sonnet-4-6`.**\nDo NOT set a reasoning model (`gpt-5`, o-series) as the synchronous content primary: they take far\nlonger than the timeout for a 2048-token generation and every call aborts with HTTP 0. (gpt-5 as a\nprimary is what caused the June 2026 network-wide content outage.)\n\n## Timeout (why 90s)\n\nContent asks for up to **2048 output tokens**; a quality model needs **25-60s** for that length.\nThe historical **30s** cURL timeout aborted generation mid-stream → cURL returns **HTTP 0**. Fixed:\n`AI_TIMEOUT_SECONDS = 90` in `config/app.php` (legacy path) AND `callAnthropic`/`callOpenAICompatible`\nin ai-provider-system.php default their cURL timeout to `AI_TIMEOUT_SECONDS` (v2.2.238). Both paths,\nor it regresses. Safe because content gen runs via the queue worker (post-response) or CLI batches,\nand admin synchronous regen is rare/one-at-a-time — not a visitor FPM hot path.\n\n## Anti-boilerplate (the SEO-load-bearing part)\n\n`_aiContentProseQualityFooter()` (ai-content.php) prepends the shared\n[Design Standards](design-standards.md) rules + an ORIGINALITY block that BANS templated openers\n(\"nestled\", \"in the heart of\", \"stands as a beacon\", \"more than just a\", \"steeped in tradition\") and\nem-dashes, and requires a page-specific opener built from real data. It is appended in BOTH paths\n(legacy always; flexible since v2.2.239). Without it, similar businesses get near-identical prose —\nthe near-duplicate cluster that triggered the [elks.club scaled-content demotion]. See the\n`project_seo_cliff_recovery` memory + [site-quality scoring](dev-api.md) for measuring boilerplate.\n\n## Failure modes (decode these fast)\n\n- **HTTP 0** — cURL timeout (slow model + tight timeout) OR connection failure. If `dz ai_ping`\n shows providers 200 in <1s, it's the model/timeout, not the network.\n- **HTTP 400 \"Your credit balance is too low\"** — the provider account is out of prepaid credits.\n This stalled a batch mid-run (~1,158 calls drained Anthropic). It IS logged (callAnthropic logs\n 4xx) but to error_logs in **UTC** while batch logs print `America/New_York` — a ~4h offset that\n makes it look unlogged. Check instantly with **`dz ai_status`** (flags billing/credit/auth).\n- **\"Content generation returned nothing\"** — `generateBusinessContent` returned null (both paths\n failed). The `regenerationRun` result carries a `detail` / `$GLOBALS['__lastContentGenError']`\n with the real per-provider cause; surface that, don't guess.\n\n## Regeneration + batch rollout\n\n`regenerationRun($businessId, 'content')` ([regeneration.php]) wraps `generateBusinessContent` with a\nreadability quality gate (keeps prior content if the new draft fails) + manifest stamp. Fleet rollout\n= worst-first over [site-quality-score](dev-api.md) boilerplate-flagged pages, rate-limited, resumable\n(re-run skips now-clean). ALWAYS `dz ai_status` first — a big batch on an empty credit balance fails\nsilently. Operator preference: drive batches via the [Dev API](dev-api.md), not raw `php -r` pasted\ninto a root shell.\n\n## Diagnostics\n\n- `dz ai_status` — live provider health + billing/credit alert + recent provider errors (UTC-correct).\n- `dz ai_ping` — minimal keyed probes to both providers (egress vs auth vs timeout).\n- `dz quality root=` — boilerplate/flag rollup to measure de-boilerplate progress.\n\nSee also [hosting infrastructure](hosting-infrastructure.md) (the queue + drain) and\n[design standards](design-standards.md) (the prose rules enforced at the source)." }, { "id": "context-city-poisoning", "title": "Context-city poisoning (never name a place after where you found it)", "type": "System", "group": "systems", "description": "Two independent creation paths named businesses after the city they were DISCOVERED from rather than where they are, putting the wrong town in 239 URLs. The pattern, the fix, and the audit.", "tags": [ "geo-anchor", "accuracy", "urls", "par-create", "prospector", "lesson" ], "path": "systems/context-city-poisoning.md", "links": [], "status": "", "generated": null, "verified": [], "stale_after": "", "sources": [], "body": "# Context-city poisoning\n\n**The bug shape:** a creation path knows two cities — the one it is *looking from* and the\none the place is *in* — and uses the wrong one. It happened twice, independently, in two\nsubsystems written months apart. Assume it will happen a third time.\n\n| Path | Used | Should have used |\n|---|---|---|\n| `parCreateSkeleton()` | the ANCHOR business's city (the page the visitor was on) | the place's own address |\n| Prospector discovery | the SWEEP CENTER's city (`$resolvedCity = $center['city']`) | the place's own address |\n\nResults in the wild: a Brooklyn bowling alley at `melody-lanes-morristown-nj.doozer.site`,\na Brentwood restaurant at `blaze-pizza-nashville-tn`, a New York restaurant at\n`tao-downtown-restaurant-jersey-city-nj`.\n\n## Why it is easy to miss\n\nThe context city is *almost* right. Most results of a Morristown sweep really are in\nMorristown, so the bug hides in the minority and every spot-check passes. It only shows up\nwhen you compare the slug against the address **systematically**. 239 of 3,439 domains\n(1,304 of which use the `city-state` slug shape) named the wrong town before anyone noticed.\n\nIt is also invisible in the product: the page content, title and schema were all correct,\nbecause those read `businesses.formatted_address`. Only the URL lied.\n\n## The rule\n\n> A city is a **fact about the place**, never about how you found it. Discovery context is\n> a hint for routing and a provenance note. It must never name anything.\n\nPar-create records this correctly for provenance: `custom_settings.discovered_on` keeps\nwhere a skeleton was seen, while `city` comes from the address. That is the right split.\n\n## The fix\n\n`parCreateCityStateFromAddress($addr)` in `par-create.php` parses the place's own city and\nstate from the address we already hold, and returns `['','']` rather than guessing when it\ncannot parse confidently, so callers fall back rather than invent. Both paths call it now.\n\nWatch the address shapes: Google returns both `\"912 Red River St, Austin, TX 78701\"` and\n`\"222 W 1st Ave, Plentywood, MT 59254, USA\"`. Strip a trailing country, then take the part\nbefore the `ST ZIP` tail. Reject a candidate that starts with a digit, which means you\ngrabbed a street line.\n\n## The audit\n\n`dz slugaudit` — scans every active domain, extracts a trailing `-city-state` slug, and\ncompares it to the address. Reports, dry-runs, repairs.\n\n**It splits the fix by risk, and that split is the important part:**\n\n- **not in the sitemap** → safe to re-slug. 217 were repaired this way.\n- **in the sitemap** → refuses unless forced, because renaming an indexed domain used to\n be a deletion plus a creation. **Resolved in v2.2.541:** see below. All 22 are renamed\n and the network now audits clean at 0.\n\n## Renaming a domain (the mechanism that was missing)\n\n`includes/domain-redirects.php`. A retired host keeps its `domains` row with\n`status='disabled'` (already means \"not serving\", so no migration) plus\n`custom_settings.redirect_to`, and `domainRetiredRedirect()` 301s it.\n\nTwo properties make it safe to leave switched on:\n\n- **Zero render-path cost.** The lookup runs only where a host has no ACTIVE domain row —\n precisely where the configure wizard used to load. A live page never reaches it. Adding\n a query to all 3,400 sites' hot path to serve a handful of retired hosts would have been\n the wrong trade.\n- **Open-redirect guard.** The target must be https, carry no userinfo, and resolve to a\n host we actually run. We are the only writer today, but a redirector that trusts a\n database string is how you become somebody else's phishing hop later.\n\nRename procedure: UPDATE the live row's `domain` (keeping id, page-view history and\nsitemap membership), then INSERT a disabled row for the old host carrying the redirect.\nThen push the new URL to IndexNow so Bing-backed search sees the move.\n\n**A correction worth keeping.** The original justification for leaving indexed domains\nalone included \"the orphan falls into the configure flow and offers a stranger the chance\nto configure somebody's business.\" That was wrong: `runRootDomainGuard()` already returned\na 302 with `x-doozer-lockdown: blocked-subdomain` for unregistered subdomains. The real\nvalue of retirement is the **permanent 301** telling a search engine the address moved,\nnot protection that already existed. Verify the claim, not just the conclusion.\n\n## Transferable lesson\n\nWhen a naming bug is found in one subsystem, **grep for the same shape everywhere else\nbefore declaring it fixed.** The instinct that caught this was simply asking whether the\nbug had happened before. Both paths had it; only one was found by working on it directly.\n\nRelated: [[the-observed-world]], [[fact-guard-identity-numbers]], [[dev-api]]." }, { "id": "design-standards", "title": "Design Standards and the Design Mirror", "type": "System", "group": "systems", "description": "One shared rule-set the generator, renderer, and admin self-diagnostic all consult — plus the mirror that scans and heals the fleet.", "tags": [ "design", "quality", "self-diagnostic" ], "path": "systems/design-standards.md", "links": [ "content-generation-and-heal", "no-dark-patterns-ethos", "muse-system" ], "status": "", "generated": null, "verified": [], "stale_after": "", "sources": [], "body": "# Design Standards and the Design Mirror\n\nThe single source of truth for \"what a tasteful Doozer site looks like\" is\n`includes/design-standards.php`. It exists so the design layers stop patching the same\nflaw in isolation. Three layers consult it:\n\n1. **Generation** — the AI content prompt (`includes/ai-content.php`) injects\n `designStandardsPromptRules()` so new content is born compliant (never bold a whole\n paragraph; only short phrases; no em dashes; 2 to 3 paragraphs).\n2. **Render** — `includes/prose-render.php` delegates to `designStandardsTameInline()`\n and `designStandardsStripEmDash()` as a safety net for non-compliant model output.\n3. **Diagnose** — the [Design Mirror](#the-mirror) scans the fleet and heals it.\n\n## Rules\n\n`designStandardsRules()` is an extensible registry. v1 rules: `over_emphasis`,\n`em_dash`, `wall_of_text`, `empty_content`. Adding a rule is one array entry.\n\n## The Mirror\n\n`includes/admin-design-mirror.php` (Admin → Design Mirror) scans live sites against the\nregistry, shows per-rule counts and percent-of-fleet with sample offenders, and offers\none-click remediation: **Heal** (reheal rules: re-saves cleaned content in place, zero\nAPI cost) and **Queue regeneration** (regen rules: enqueues content jobs). It never\nauto-acts; the operator controls spend.\n\n## The rule\n\nNew design-shape problems get a registry rule, NOT a one-off override. That is the\nanti-bandaid principle that motivated this system. See the\n[content generation and heal](../processes/content-generation-and-heal.md) process and\nthe [no dark patterns](../decisions/no-dark-patterns-ethos.md) ethos.\n\n## The regeneration readability gate\n\nThe [unified regeneration engine](../processes/content-generation-and-heal.md)\n(`includes/regeneration.php`) uses this registry as its safety net: after generating new\ncontent it scans, heals once, and rolls back to the prior content if the result is still\nbroken, so a regeneration can never leave a live site worse. What counts as \"broken\" is\nderived from the registry, not hardcoded: `designStandardsBlockingRuleIds()` returns the\nrules a heal cannot fix (`fixable = 'regen'`, currently `empty_content` and `wall_of_text`).\nCosmetic rules (`fixable = 'reheal'`, e.g. over-bold prose and em-dashes) are auto-healed\nand NEVER block. This encodes the operator principle: reject broken or unreadable output,\nnever reject a site for being bold or expressive. Any future `regen`-fixable rule joins the\ngate automatically.\n\n(History worth keeping: this gate shipped dead in v2.2.205 and was a silent no-op until\nv2.2.211 — it scanned for a severity vocabulary and scan shape the registry never produced.\nThe lesson, again: verify the wiring actually fires, do not assume it does.)\n\n## Scope: content shape, not visual CSS\n\nThis system governs the SHAPE of generated CONTENT (prose emphasis, em dashes, wall of\ntext, emptiness). Visual CSS safety, such as AA contrast and guaranteeing an outline\nbutton is actually visible, is a separate concern handled at render time by the\n[Muse System](muse-system.md)'s composition layers (`muse-contrast.php` plus the\nbutton-visibility safety in `muse-apply.php`). If a control is invisible or low-contrast\non live sites, look there, not in this registry." }, { "id": "directory-framework", "title": "Directory Multi-View Framework", "type": "System", "group": "systems", "description": "The shared Grid / List / Map / Events view system that every directory surface (root, Cloud, NBMN) renders through.", "tags": [ "directory", "views", "grid", "list", "map", "events", "framework" ], "path": "systems/directory-framework.md", "links": [ "the-network", "clouds", "nearbymenow", "shared-business-card", "livemusictonight", "muse-system" ], "status": "", "generated": null, "verified": [], "stale_after": "", "sources": [], "body": "# Directory Multi-View Framework\n\nOne framework renders every directory surface in the [network](the-network.md) —\nroots, [Clouds](clouds.md), [NearByMeNow](nearbymenow.md) — in multiple views\nwithout each surface reimplementing them. `includes/directory-views.php` owns the\nregistry and the JS contract; a view is toggled by an `html[data-dir-view]`\nattribute, and a surface opts into a view by rendering a\n`data-dir-view=\"\"` panel and flipping it ready.\n\n## The views\n\n- **Grid** (live) — the default card wall, using the shared\n [business card](shared-business-card.md).\n- **List** (live) — dense CSS rows with a subdomain/site pill.\n- **Map** (live) — a shared Leaflet engine fed by `?ajax=root_map_markers` /\n `cloud_map_markers`; listings carry lat/lng.\n- **Events** (live) — upcoming events per business via\n `businessUpcomingEventsBulk()` (`includes/business-events.php`), fed by\n `root_events` / `cloud_events` ajax; vertical directories like\n [Live Music Tonight](livemusictonight.md) render from `marquee_events`.\n\n## Distance sort\n\nRoot and Cloud both support distance sort (`resolveRootDomainOrder` /\n`cloudFetchListings` + a shared geo helper + `?e=geo`), so \"nearest first\" works\nanywhere.\n\n## Why one framework\n\nAdding a view once lights it up across every surface. The cost is the shared\ncontract's discipline: a new card action must be registered where each host routes\nits actions (e.g. NBMN routes its own card actions in `nearbymenow/index.php` — a\nnew action added only to the generic handler silently no-ops there). This is the\ndirectory analogue of the \"one renderer, many surfaces\" principle behind the\n[business card](shared-business-card.md) and [Muse system](muse-system.md)." }, { "id": "atlas", "title": "Doozer Atlas (outward AI emission)", "type": "System", "group": "systems", "description": "The public, per-entity knowledge contract Doozer emits so external AIs can ingest the network — the outward-facing twin of the inward Brain.", "tags": [ "atlas", "ai", "knowledge", "okf", "well-known", "outward" ], "path": "systems/atlas.md", "links": [ "okf-adoption", "livemusictonight" ], "status": "", "generated": null, "verified": [], "stale_after": "", "sources": [], "body": "# Doozer Atlas\n\nThe **Atlas** is Doozer's outward AI knowledge emission: a public, structured\nprojection of what the network knows, published so external AIs and agents can\ningest it. It is the mirror image of the [Brain](../decisions/okf-adoption.md) —\nBrain is inward (how Doozer understands itself, this bundle you are reading), Atlas\nis outward (how the world's AIs understand Doozer).\n\n## The contract\n\nEvery entity emits a public `/.well-known/doozer-atlas` document\n(`okfEntityFor*()` in `includes/okf-engine.php`) for its type: **Business**,\n**Cloud**, **Directory**, **Event**. The Atlas owns the CONTRACT — a derived\nprojection over live data. There is **no separate graph database**; the Atlas is\nmaterialized from the same tables that render the pages, so it can never drift from\nreality.\n\n## Why it exists\n\nSearch is shifting from links to answers. If an AI is going to answer \"what's a\ngood florist near West Milford,\" Doozer wants the network to be the citable,\nmachine-readable source, with accurate structured data (hours, geo, niche,\nreviews, events). The [JSON-LD on vertical directories](livemusictonight.md) is the\nsame instinct at the page level. This is a moat: a network that is legible to AIs,\nby design, is the one that gets cited.\n\n## Relationship to this bundle\n\nThis `knowledge/` OKF bundle (exportable as one portable `.zip` via Admin → Doozer\nBrain) is the Brain. The Atlas is the per-entity public feed. Both use the same OKF\nengine and the same \"it's just files / it's just structured data\" philosophy\n(see [OKF adoption](../decisions/okf-adoption.md)). Grow the Brain and the Atlas\ngets richer context to project." }, { "id": "doozer-digest", "title": "Doozer Digest (AI daily newsletter)", "type": "System", "group": "systems", "description": "An AI-written daily email — a public reader edition and an operator admin edition — built from real platform signals.", "tags": [ "digest", "newsletter", "email", "growth", "ai", "signals" ], "path": "systems/doozer-digest.md", "links": [ "the-network", "admin-health-tools", "marketing", "the-value-model" ], "status": "", "generated": null, "verified": [], "stale_after": "", "sources": [], "body": "# Doozer Digest\n\nAn AI-composed daily email, in two editions, each built from the same real\nplatform signals the rest of the network runs on (never invented).\n\n## Public edition\n\nA reader-facing daily digest (new sites, notable local businesses, events) that\nturns the growing [network](the-network.md) into a reason to come back. Shipped\npieces: the digest generator, an AI intro, and sponsor slots. Next: recipient\nmanagement / opt-in and the send cron.\n\n## Owner edition (per-business stats)\nA third edition for a CLAIMED business's owner: their numbers in their inbox\n(\"people are finding you\"). `includes/digest-owner.php` — `digestBusinessStats()`\naggregates views, calls, directions, website clicks, saves, and leads for a window\nplus the prior window (trend arrows) and lifetime reach, all from the same real\nsignals (page_views, click_events, lb_follows, nbmn_lead_requests, shortlinks).\nTwo tiers, one template: **Doozer+** gets all six metrics with trends; **claimed\n(free)** gets two headline numbers + an audience-aware upsell via\n`doozerPlusOfferFor()`. Tier resolves through the implicit-verification rule\n(admin_email authoritative, else scraped email -> owner's `lb_users.tier`). Preview\nwith `dz digest owner= [tier=plus|free] [render=1]`. Built and previewable;\nNO send path is wired yet (recipient management + cadence are operator-approved).\n\n## Admin edition\n\nAn operator-facing daily brief: growth, revenue, key metrics, and an\n\"idea-of-the-day.\" It is the human-readable companion to the\n[admin health tools](admin-health-tools.md) — the same fleet supervised through a\nmorning email instead of a dashboard sweep. It shares the signal miners with\n[Marketing](marketing.md) (changelog, LeadBuilder metrics, recent discoveries), so\nthe numbers are the ones that actually run the business.\n\nBoth editions are downstream of the [value model](../decisions/the-value-model.md):\nthe public edition drives retention/discovery, the admin edition drives operator\nawareness. Roadmap order: NBMN demand-gen → Admin Digest → [Admin Alerts](admin-health-tools.md).\nSee [[project_doozer_digest]]." }, { "id": "doozer-town", "title": "Doozer Town and the Board Game view", "type": "System", "group": "systems", "description": "doozer.town builds a page for every town in America the first time somebody asks for it, sorts its businesses onto ten colour groups, and can show any Doozer Cloud as a property board. Cost model, grouping rules, the edge blocker, and what to watch.", "tags": [ "doozer-town", "clouds", "growth", "board", "groups", "geo", "self-building" ], "path": "systems/doozer-town.md", "links": [], "status": "stable", "generated": { "by": "claude-fable-5-1", "at": "2026-09-11" }, "verified": [ { "by": "jon-berry", "at": "2026-09-11" } ], "stale_after": "2027-03-01", "sources": [ "places ledger", "clouds table", "job queue", "live pages" ], "body": "# Doozer Town and the Board Game view\n\n**The operator's two ideas (Sept 2026), which turned out to be one:** a Cloud view that\nturns any cloud into a Monopoly-style board with businesses as property cards grouped\ninto colour-coded categories; and `doozer.town`, dynamic self-building town clouds for\nevery town in every state. The grouping the board needed is the structure the town page\nneeded. Built in one pass as v2.2.615.\n\n## The address is the instruction\n\n`west-milford-nj.doozer.town` = West Milford, NJ. The slug parser accepts\n`-` only; the state must be real. Anything else is a 404, not a town.\n\nA visit resolves the slug in cost order (`townEnsure()` in `includes/town-engine.php`):\n\n| step | source | cost |\n|---|---|---|\n| existing town cloud | `clouds` row by host | $0 |\n| businesses we hold in that city/state | centroid of our own geo-verified rows, 6 mi radius | $0 (1,955 city/state pairs qualify today) |\n| unknown town | one Google geocode | $0.005, bot-gated (`_nbmnRequestIsBot`), `town_create_max_per_hour` (30), and only when the result names the same place in the same state |\n\n`asdfgh-nj` returns `not_a_place`; a crawler on an unknown town gets a 404 \"not on the\nboard yet\" and spends nothing. A town is a normal `clouds` row (`cloud_type=geo`,\n`visibility=unlisted` so Discover Clouds stays curated) with a `town` block in\n`criteria` (city, state, county, slug, source, last count). It rides the cloud engine\nunchanged, so saves, counts and the card renderer all work. **A radius, not a city-name\nmatch**, is what makes \"serves West Milford\" true: Hewitt, Newfoundland, Oak Ridge,\nRingwood and Greenwood Lake sit inside it.\n\n## The ten groups\n\n`townGroups()` / `townGroupKeyFor()`: Eat & Drink, Shops, Home & Trades, Health,\nSelf-care, Auto & Around, Civic & Community, Money & Pros, Stay & Visit, Utilities &\nEssentials, plus Everything Else. Resolution order: explicit slug/type rules (because\n`businesses.primary_niche` mixes catalogue slugs and Google types, and a business's\n`types` JSON is consulted too), then the catalogue category, then keywords in the name.\nAn empty group is an **open lot** on the page and on the board and links straight to\nFind, because the brand's mark is a grid with one cell still open. West Milford after\nthe first pass: 355 businesses, 10 of 10 groups, 34 in Everything Else.\n\n## Money moves only on a tap\n\nRendering a town costs nothing. Find calls the existing `?e=nbmn_populate`\n(cache-first, bot gate, per-IP and global paid caps, the $10/day Places cap) around the\ntown centroid; Build posts to the existing `?e=nbmn_build_place` (hourly cap) and lands\nthe site on doozer.site, where the town's radius picks it up on the next render. The\ncounty eyebrow is one Magellan geocode per town, once, and only for a human.\n\n## The Board Game view\n\n`renderCloudBoardView()` in `includes/cloud-board-view.php`, `?view=board` on any\ncloud and on every town. Forty spaces: corners Start / Saved / Free parking / Build,\nnine per side. `boardDealSpaces()` deals a balanced hand: every non-empty group gets a\nspace, empties get an open lot, the rest is largest-remainder proportional, capped by\nsupply. More than 36 members lists the whole deck underneath (CSS columns, not a grid;\na grid left three empty columns beside one 66-item group). `?deal=n` reshuffles within\ngroups with the top third kept as anchors. Tapping a space opens a `

` deed with\nphoto, rating, address, call and visit. Pure renderer, spends nothing.\n\n## The edge (Plesk)\n\nEvery wildcard root is a `ServerAlias *.` line in the subscription's additional\nApache directives (HTTP and HTTPS both). On the day it shipped `*.doozer.town` briefly\nanswered from another vhost until that line was in; `curl --resolve` against the origin\nIP is the only way to see past Cloudflare when that happens. With the alias live,\n`town_wildcard_live=1` makes the apex path form `doozer.town//` a 301 to the real\naddress; the path form stays as a permanent link shape.\n\n## Operate it\n\n- `dz town slug=-` resolves (creating from inventory) and reports groups,\n also-serves and nearby towns; `create=0` to look only; `force=1` to allow the\n geocode path from the dev channel (its curl UA reads as a bot otherwise).\n- `dz town list=1 [state=NJ]`.\n- Telegram kind `town_created`.\n- Town pages are `noindex` under 5 businesses and on every filtered view.\n\n## The contract: a person arrives, the site builds\n\nEvery skeleton exists for free until a person opens it; that visit fetches the\ndetails (photos, website, phone, hours), writes the page, and the site is built by the\ntime they look around. The operator's rule (10 Sep 2026): **if a person is standing on a\nsite that has not built itself, that is a bug**, never a budget decision. Two\nconsequences. Paid backfills are not the way to fill boards; the visit is. And the\ncrawler checks that protect the budget must never catch a person: no bare IP-range\nguesses (a /16 for Cloudflare's renderer also matched iCloud Private Relay), only named\nagents, datacenter first octets, cached reverse DNS, and our own capture marker.\n\n## Pre-filling a town (the par-create method)\n\n`dz town prefill=1 slug=` is a dry run: for each group's niches it says whether the\nnearby-discover bucket is warm (somebody already paid for it: $0 skeletons) or cold (one\nNearby Search, $0.035). `live=1` creates skeletons from warm buckets; `budget_usd=2`\nlets it spend on cold ones, thin groups first. A full town is ~58 niches, about $2.\nSkeletons land on doozer.site (noindex), are enriched by their first human visitor\n(~$0.06 to $0.12), and appear on the board immediately through the radius. Pace it\ninside the Places hourly ceiling (one town an hour) and the daily cap.\n\n## What the first day cost, and why it will not again\n\n$10 in a day: $8.85 was an image crawler fetching uncached gallery photos on 284\nbusiness sites in four minutes, not the towns ($0.63). The photo proxy now refuses paid\nfetches for crawlers, the ledger has an hourly ceiling, and card photo sizes snap to the\ncached ladder. The town page itself renders for $0.\n\n## Where it sits in the ecosystem (Sept 2026)\n\nFour surfaces, one loop. **NearByMeNow** is search: what are you looking for.\n**Doozer Town** is place: everything that serves one town, ranked. **Business sites**\nare the entity: one page per place, the thing the other two point at. **Clouds** are\ncuration: a Keeper's chosen set. The loop is wired both ways: every business site's\n\"Around the neighborhood\" links to its town board, every board links to every site, the\nnetwork footer carries Doozer Town everywhere, and the apex sitemap (221 indexable\ntowns) goes to Bing by IndexNow. Bing is the channel; towns are the pages Bing can rank\nfor \" businesses\" that a single business site never could.\n\nGrowth runs through the town: the pre-fill trickle feeds par-create from the biggest\nboards, skeletons appear on the board at $0, a person's first visit enriches one, the\nranking decides who leads a group, and sponsorship (a labelled slot above the ranked\nlist, never inside the score) is where the revenue lives when it comes. Honorary\nDoozers are the people who press Find and Build on a board they care about.\n\nEvery part of that spends only on a person, and every guard has a ledger line.\n\n## What is deliberately not done yet\n\nNo Atlas or llms.txt entry for towns yet (sitemap, robots, footer link and the\nsite-to-town link shipped 10 Sep); no town list beyond what our inventory implies (a Census gazetteer would let the apex list every\nplace in a state). The group rules will keep needing words added as Everything Else\nshows what the rules miss.\n\nRelated: [[clouds]](clouds.md) · [[the /now surface]](the-now-surface.md) ·\n[[growth engine]](growth-engine.md) · [[brand system]](brand-system.md) ·\n[[Magellan and the feed pond]](magellan-and-feeds.md)" }, { "id": "email-tracking", "title": "Email Open Tracking", "type": "System", "group": "systems", "description": "A 1x1 pixel in every outbound email; opens recorded with device/geo/bot-flag; three operator alert signals plus data for the digest.", "tags": [ "email", "tracking", "intent", "comms", "alerts", "analytics" ], "path": "systems/email-tracking.md", "links": [ "doozer-digest" ], "status": "", "generated": null, "verified": [], "stale_after": "", "sources": [], "body": "# Email Open Tracking\n\nEvery email `doozerSendEmail()` sends (the single mail chokepoint) gets a unique\n1x1 tracking pixel and an `email_sends` row. `includes/email-tracking.php`.\n\n## What is captured\n- **Pixel endpoint** `?e=eopen&t=` (sessionless, returns a 1x1 gif, records\n AFTER flushing so it never adds latency). `email_opens` rows carry device\n (mobile/desktop), coarse geo (`CF-IPCountry` header when present), `ip_hash`,\n and a **bot flag**.\n- **Bot / prefetch detection**: Apple Mail Privacy Protection, Google/Yahoo image\n proxies, and any open within ~8s of send are flagged `is_bot=1` and kept out of\n the alerts (still counted separately). `open_count` vs `human_open_count`.\n- **Age is computed in the DB** (`TIMESTAMPDIFF(SECOND, sent_at, NOW())`), never\n from PHP `time()` vs a MySQL timestamp — that mismatch false-flags prefetches.\n\n## The three alert signals (📬 `email_open` ping)\n1. **Old email opened** (>= 14 days after send) — the headline: a dormant thread\n reawakening means something is up. Alert-level, 6h re-throttle per send.\n2. **Unusual attention** — >= 4 human opens in 20 min. Hourly re-throttle.\n3. **High-signal first open** — first human open of an important kind\n (`lead_forward`, `claim`, `owner_digest`, `lead`).\n\nAll opens are stored regardless, so the [Digest](doozer-digest.md) can report\nopens / devices / repeat-rate even when no alert fires. `dz emailtrack` for an\noverview; `dz emailtrack do=selftest [age_days=]` to exercise the flow.\n\n## Related\nTag an email with `['kind' => …, 'business_id' => …]` in the `doozerSendEmail`\nopts so alerts and the digest can attribute it. `['no_track' => true]` opts out.\nThe daily digest email to the operator is itself tracked (dogfooding).\nSee [[doozer-comms]] for the ping plumbing and [[notify-generously]] ethos." }, { "id": "enrichment-store-links", "title": "Enrichment Store Links (commerce \"Shop Now\" CTAs)", "type": "System", "group": "systems", "description": "Turning a business's real online store into a tasteful commerce CTA, with a confidence gate so we never send a visitor to a bare marketplace homepage.", "tags": [ "commerce", "store-links", "shop-now", "monetization", "confidence-gate" ], "path": "systems/enrichment-store-links.md", "links": [ "location-data-enrichment", "the-value-model", "no-dark-patterns-ethos", "the-mission", "money-clouds" ], "status": "", "generated": null, "verified": [], "stale_after": "", "sources": [], "body": "# Enrichment Store Links\n\nWhen [enrichment](location-data-enrichment.md) finds a business's real online store,\nthe site can surface a \"Shop Now\" CTA — a small commerce affordance and an\naffiliate/referral surface (see [the value model](../decisions/the-value-model.md)).\nThe hard part is not finding a link; it is not surfacing a BAD one.\n\n## The confidence gate (the load-bearing part)\n\nThe original extraction (`_extractExternalStores`) host-matched ANY marketplace\nlink, so roughly half the captured \"stores\" were not the business's own store at\nall — bare `amazon.com` homepages, search pages, \"recommended\" rails. Sending a\nvisitor there is a dead end and erodes trust ([no dark patterns](../decisions/no-dark-patterns-ethos.md),\n[the mission](../decisions/the-mission.md)). The fix: `storeLinkConfidence()` scores\na candidate, an admin audit panel surfaces low-confidence ones, and a **render-time\ngate** hides anything that does not clear the bar. A CTA only shows when we are\nconfident it is the business's real store.\n\n## Status\n\nThe confidence scoring + audit panel + render gate shipped; extraction hardening and\na backfill of already-captured links remain. This is the same discipline as the\n[store-link confidence in Money Clouds](money-clouds.md) affiliate feeds and the\n\"Shop Now\" on business sites: better to show nothing than to show a wrong link.\nSee [[project_enrichment_store_links]]." }, { "id": "events-to-machines", "title": "Events to machines — a live event is only half published until a machine can read it", "type": "System", "group": "systems", "description": "The pipeline that takes real events from public feeds onto a Doozer page AND emits them as schema.org Event, plus the timezone rule that makes the data correct. The foundation for gohe.re Gatherings.", "tags": [ "events", "schema-org", "ai-discoverability", "feeds", "gatherings", "timezone", "aeo" ], "path": "systems/events-to-machines.md", "links": [], "status": "", "generated": null, "verified": [], "stale_after": "", "sources": [], "body": "# Events to machines\n\n**The operator's goal, stated 2026-08-23:** Doozer sites should be *perfectly tuned for AI\nagents to find, understand and reference*, as well as for search engines and people.\n\nThat goal exposed a gap the day after events started working. Lodge and venue pages were\ncarrying real, current events — a visitor could read \"Friday Fish Fry, Aug 28, 4:00 PM\"\nperfectly well. The page emitted `LocalBusiness` and `FAQPage` and **no `Event` at all**.\nSo an AI agent, a search engine, or any structured-data consumer had no idea the event\nexisted.\n\n> **A live event is only half published until a machine can reference it.**\n\n## The pipeline\n\n public feed -> bound by Magellan -> stored as facts -> rendered for humans\n -> emitted as schema.org Event\n\nSources today (all keyless, all legitimate):\n\n| source | Magellan service | what it yields |\n|---|---|---|\n| public Google Calendar embed | `gcal` | full event feed with recurrence ([[magellan-and-feeds]]) |\n| Ticketmaster / Marquee | `ticketmaster` | ticketed shows at known venues |\n| schema.org on the business's own site | — | `Event` where present (rare: ~0 in sample) |\n\n`businessUpcomingEvents()` (`business-events.php`) is the single read path: gcal first\n(a business's own calendar outranks anything we infer), then Marquee. **One events\nsurface, many sources** — adding a feed must never add a second events UI.\n\n`buildEventsJsonLd()` (`schema-org.php`) emits from **the same call the page renders**, so\nthe structured data can never drift from what a human sees.\n\n## THE TIMEZONE RULE (this is the correctness problem, not a detail)\n\n`startDate` is only meaningful with a real UTC offset, and **a wrong offset is worse than\nnone — it moves the event.**\n\n- Rows that carry the event's own zone (`tz`, from the calendar) get a true offset:\n `2026-08-23T13:00:00-07:00` for a San Diego lodge, generated on an Eastern server.\n- Rows with no zone emit a **local date-time with no offset** — valid ISO 8601, honest\n about what we know. We do **not** stamp the server's zone onto a venue three time zones\n away.\n- All-day events emit a date only.\n- Anything already past is dropped, never advertised.\n\nThis is the same failure that once displayed a San Diego lodge's Friday dinner as Saturday\nmidnight. It is not to be reintroduced through the structured-data path.\n\n## Where this is going\n\nEvery public gathering at a real place is a candidate for a **gohe.re Gathering** (QR,\nattendees, media, memories, chat, find-each-other map), and later a **wuz.ai** memory\nlayer. Both need each event to be an addressable, machine-readable entity first — which is\nwhat this node is the foundation for. Event categories worth ingesting as feeds appear:\nlive music, karaoke, trivia, bingo, tricky trays, fundraisers, bike nights, car shows,\ncruise nights, meetups, showtimes.\n\n**Facebook is not a source.** Page events cannot be read: direct fetch and mbasic both\nreturn HTTP 400, a reader returns a login wall, and the Graph API Page `/events` edge was\ndeprecated in 2018. Bind `facebook` for identity only, never scrape. Do not re-litigate.\n\nRelated: [[magellan-and-feeds]], [[event-feeds]], [[ai-discoverability]],\n[[gatherings-and-social]], [[the-observed-world]]." }, { "id": "fact-guard", "title": "Fact-Guard (the accuracy net)", "type": "System", "group": "systems", "description": "A conservative healer that catches and corrects factual drift in AI-generated content (e.g. lodge/post identity numbers) at both the DB boundary and render.", "tags": [ "fact-guard", "accuracy", "ai", "content", "healing", "quality" ], "path": "systems/fact-guard.md", "links": [ "the-doozer-story", "content-generation", "elks-root-theme", "location-data-enrichment", "free-tier-render-gotchas" ], "status": "", "generated": null, "verified": [], "stale_after": "", "sources": [], "body": "# Fact-Guard\n\nFact-Guard is a safety net for the one thing AI content must never get wrong:\n**verifiable facts.** A tasteful site that states the wrong lodge number or a\nmangled name is worse than a plain one — it breaks trust, which is the top of the\n[quality bar](../decisions/the-doozer-story.md).\n\n## What it does\n\n`factGuardHeal($content, $biz, $opts)` (`includes/fact-guard.php`) runs over\ngenerated content and conservatively corrects factual drift:\n\n- `factGuardDeriveIdentity($name)` parses a business name for a fraternal/civic\n identity + number (Lodge / Post / Chapter / Council / Aerie / ... No. NNNN).\n- `factGuardFixIdentityNumbers($data, $keyword, $number)` repairs a wrong number\n ONLY when a real separator is present (`No.` / `#` / `Number`), so it never\n invents or over-corrects.\n\nIt is **conservative by design** — it fixes provable drift and leaves everything\nelse alone. It runs at two boundaries: at generation\n(`factGuardHeal(...)` after decode in [content generation](content-generation.md))\nand at the DB boundary (hooked into `saveGeneratedContent()`), so both fresh\nbuilds and re-saves are guarded.\n\n## Why it exists\n\nThe [Elks fleet](elks-root-theme.md) surfaced it: an AI given a lodge name would\noccasionally restate the lodge number wrong. Fact-Guard is the general pattern —\nwhere a fact is derivable from hard input (the name, the Places data), verify the\noutput against it. It complements the [GIGO principle](location-data-enrichment.md):\nGIGO says better input makes better voice; Fact-Guard says never let good input get\ncorrupted on the way out. Extend it as new verifiable fact classes appear.\n\n## Prevention beats correction: feed the facts into generation\n\nFact-Guard is the net, not the first line. The better fix for most inaccuracies is\nto hand the generator the fact so it never invents a wrong one — no per-fact trap.\nExample (v2.2.330): an AI hero claimed a barbershop was open \"Six Days\" while its\nhours showed closed Sunday AND Monday (open 5). Root cause: the content-generation\ncontext (`ai-content.php`) fed name/address/rating/reviews but NOT the hours. Fix:\ninject the real `weekday_text` plus a computed \"Open N days a week (closed …)\" line.\nThe model can't invent a schedule it's been handed. Operator rule: prefer accuracy\nby GIVING the model the fact over trapping for a specific mistake — same spirit as\nthe [muse custom_css prompt fix](free-tier-render-gotchas.md). Fact-Guard stays for\nthe classes a prompt can't reliably prevent (e.g. an identity number the model\nmangles even when told)." }, { "id": "fact-guard-identity-numbers", "title": "Fact-guard — org identity numbers, and the hole a conservative regex left", "type": "System", "group": "systems", "description": "How the accuracy net corrects a wrong Lodge/Post number, why the safe-looking regex silently no-opped, and why over-correcting it is worse than the original bug.", "tags": [ "accuracy", "fact-guard", "elks", "content-generation", "trust" ], "path": "systems/fact-guard-identity-numbers.md", "links": [], "status": "", "generated": null, "verified": [], "stale_after": "", "sources": [], "body": "# Fact-guard — org identity numbers\n\n`includes/fact-guard.php` is the network accuracy net: it overwrites AI drift on facts we\nhold canonically. Rule 1 is the **organization identity number** (Elks/Moose \"Lodge\",\nVFW/American Legion \"Post\", Eagles \"Aerie\", K of C \"Council\"). Two hooks, zero API cost:\na render-layer heal in `business-site.php` and a DB-boundary heal in\n`saveGeneratedContent()`. Repair tool: `dz factguard` (audit / per-business decontaminate /\n`heal=stored`).\n\n## The lesson: a conservative regex can no-op silently and still look right\n\nShipped v2.2.318, the corrector required a `No.` / `Number` / `#` separator between the\nkeyword and the digits, deliberately, so ordinary prose (\"post 2020 renovation\") could never\nbe mangled. It was correct and it was tested. But the hallucination in the wild is uniformly\nthe **bare** form: *\"Elks Lodge 339 in Plentywood\"*. The heal matched nothing, changed\nnothing, threw nothing, and read as working for two months (operator note #18, July 20 2026).\n\nTwo things compounded it:\n\n- Both `factGuardHeal()` call sites passed **no `$opts`**, so the number was derived from\n the business NAME. Many lodges are scraped as plain \"Elks Lodge\" or \"Elk's Club\" with no\n number at all, so the heal was a guaranteed no-op for exactly the sites that needed it.\n- The generator was never told the number. `businesses` has **no domain column** and both\n generation entry points load the row with a bare `SELECT *`, so the subdomain — the one\n identity fact we MINT rather than scrape — was out of scope in `buildBusinessContext()`.\n Meanwhile the prose brief asks for \"a concrete fact: founding/charter year\". The prompt\n rewarded inventing precisely the thing nothing supplied.\n\n**Takeaway: a healer that cannot report what it changed is indistinguishable from a healer\nthat does nothing.** `dz factguard heal=stored` now emits a real before/after per row.\n\n## The harder lesson: over-correction is worse than the original bug\n\nThe first cut of the bare-form rule rewrote every lodge number in the content to ours. On\nlive pages that produced:\n\n- `Freemasons of Newark Lodge #83` → `#1249` (a Masonic lodge sharing the building)\n- `a party of six from Lodge 401` → `Lodge 1249`\n- `close relationship with Dallas Elks Lodge 71` → `Dallas Elks Lodge 2485`\n\nEach trades one wrong fact for a **false claim about a different real organization**.\nEnumerating \"foreign cues\" kept losing, so the rule was inverted: only correct a mention\nthat is positively OURS. A mention is skipped when preceded by a foreign-order or\nother-lodge cue, by `from`, or by a **place name that is not one of our own city tokens**.\n\n> Leaving another lodge's number intact is not a false claim about us. Changing it is a\n> false claim about them. The tie always breaks toward leaving it.\n\nThe cost of that conservatism is real and accepted: a handful of pages simply never state\ntheir own number in prose. That is a gap, not a lie.\n\n## Two traps worth remembering\n\n- **Compare numerically.** The Order zero-pads: `?LodgeNumber=0031` is lodge 31. A string\n compare flagged ~130 correct rows as contaminated and would have rewritten them all.\n- **Compare decoded structures, not JSON.** Re-encoding `ai_generated_content` differs in\n slash/unicode escaping even when nothing changed, which reported ~170 phantom rewrites.\n- **Single-digit charter numbers are real** (Louisville #8, St. Louis #9). A `\\d{2,6}` floor\n silently skipped them.\n\n## The root cause was DATA, not tone\n\nPlentywood (business 1658) had the wrong lodge in its own record: `website` pointing at\n`LodgeNumber=339`, `email` `secretary@alleghenyelks.org`, a Pittsburgh `412` phone in\n`deep_research`. Enrichment scraped the wrong lodge; the generator faithfully wrote what it\nwas fed. Signal in, signal out. Seven elks businesses had a `LodgeNumber=` URL contradicting\ntheir subdomain, two of which still got the right number in content, so the bad-website\nproblem is slightly wider than the bad-content one.\n\n**That leaked ownership, which mattered more than the copy.** With `admin_email` NULL, the\nscraped `email` IS the implicit owner ([[project_implicit_verification]]), so an officer of\nthe Pittsburgh lodge could have signed in by magic link and managed a Montana lodge's site.\nThree businesses were in that state. A scrape of the wrong entity is untrustworthy\nfield-by-field, so decontamination drops the derived scrape wholesale\n(`deep_research.contact_email`, `additional_phones`, enrichment provenance) and re-points\n`website` at the lodge's own canonical page. Google's geo-verified phone and address are\nnever touched, and an email naming our own lodge or city is KEPT.\n\nVerification method that settled every case: fetch `elks.org/lodges/home.cfm?LodgeNumber=N`\nand compare its city/ZIP to the business's `formatted_address`. All seven subdomains proved\ncorrect at ZIP level; the stored websites were the wrong ones.\n\n## The number is the least of what a wrong-lodge scrape carries\n\nAfter the websites were corrected, Flora IL still linked to **Carmichael CA's\nFacebook** and rendered **Carmichael's photo as its hero**, because the first pass\ncleared four keys and left `social_media`, `images`, `logo_url`. Camillus NY had a\ncorrect website but only **Chicago lodge 2367's** images. Wrong photo and wrong\nsocial link are worse than a wrong number, and neither is reachable by a text healer.\n\nDetection took three tries; the failures are the useful part:\n\n- A loose `~elks(\\d+)~` read Facebook page ids and **image dimensions**\n (`WoburnStonehamElks-150x150.png` → \"150\") as charter numbers, condemning 5 clean rows.\n- Scoping to elks.org URLs still flagged lodges that legitimately embed another\n lodge's asset (a state president's photo, a shared bingo graphic).\n- **The rule that holds:** a foreign lodge number in an elks.org asset path is damning\n only when **none** of the assets are ours.\n- `json_encode` writes `\\/`, so a char class stopping at the backslash truncates the\n URL to `www.elks.org` and hides the path carrying the number. Un-escape first.\n\n`purge=1` forces the purge for a hand-verified case, because repairing the website\nfirst removes the signal the detector keys on.\n\n## Adjacent defect, deliberately not fixed here\n\nTwo businesses (685, 1601) carry a **spurious second elks domain** whose lodge number\ndiffers from the one their content correctly states. That is a domain-mapping problem, not\nan accuracy one; `dz domdupes disable=` is the tool. `dz factguard` refuses any\nbusiness whose elks domains disagree, so it cannot \"fix\" one of these by corrupting good data.\n\nSee also: [[elks-root-theme]], [[content-generation]], [[source-of-truth-cache]], [[dev-api]]." }, { "id": "gatherings-and-social", "title": "Gatherings + Social (events, check-ins, the human layer)", "type": "System", "group": "systems", "description": "The roadmap surfaces that add real-time human signal — events/gatherings (GoHe.re), check-ins (wuz.ai), and how they enrich every business site.", "tags": [ "gatherings", "events", "checkins", "gohere", "wuzai", "social", "roadmap" ], "path": "systems/gatherings-and-social.md", "links": [ "location-data-enrichment", "livemusictonight", "directory-framework", "user-hotspots", "the-network", "clouds", "atlas", "the-flywheel" ], "status": "", "generated": null, "verified": [], "stale_after": "", "sources": [], "body": "# Gatherings + Social\n\nThe strongest content lever for a business site is not better prose — it is **real\nhuman signal**: what is happening there, who was there, what they thought. This is\nthe [enrichment](location-data-enrichment.md) direction made social, and mostly\nroadmap (some live).\n\n## Events (live pieces)\n\n`marquee_events` (Ticketmaster via `marquee-engine.php`) powers vertical\ndirectories like [Live Music Tonight](livemusictonight.md) and the Events view in\nthe [directory framework](directory-framework.md). An `lmt_interest` demand graph\nrecords view / interested / ticket-click signals, feeding an admin \"Live Music\nDemand\" build loop: real demand decides which venue sites to build next.\n\n## GoHe.re — gatherings (roadmap)\n\nThe events/gatherings root. The **Events Waterfall** strategy builds backwards:\nticketed events → venue sites → calendars → Global Gatherings. \"Instant\nGatherings\" and \"Wuz-for-One\" let anyone create a gathering for any place + time.\nThis is the surface where user-supplied events, comments, and photos flow into the\n**true voice** of each location.\n\n## Check-ins — wuz.ai (roadmap, flaky-live)\n\nCheck-in / \"Wuz\" toolbar signals who is where, now. `user_hotspots`\n([user hotspots](user-hotspots.md)) already derive a coarse home centroid for\nsigned-in users to enable proximity features.\n\n## Why it matters\n\nPer the [GIGO principle](location-data-enrichment.md), a site sounds like itself\nonly when fed real signal. Events, check-ins, and gathering photos/comments are\nthat signal, and crucially they feed **every** surface on the shared\n[data spine](the-network.md) — the business site, the [Clouds](clouds.md), the\nvertical directories, and the [Atlas](atlas.md) emission. One person RSVPing to a\nshow enriches the venue's site, its directory listing, and what AIs know about it.\nThat is [the flywheel](the-flywheel.md) reaching into the physical world." }, { "id": "doozer-prospects", "title": "Hot Leads — the internal Doozer-sales CRM", "type": "System", "group": "systems", "description": "Businesses are OUR prospects. Doozer-awareness scoring (claimed + postcard engagement + leads we deliver + live site) ranks who is warm enough to pitch Doozer+. The Internal Affairs Division of LeadBuilder.", "tags": [ "prospects", "hot-leads", "crm", "doozer-plus", "awareness", "monetization", "leadbuilder", "machi" ], "path": "systems/doozer-prospects.md", "links": [ "ai-postcards" ], "status": "", "generated": null, "verified": [], "stale_after": "", "sources": [], "body": "# Hot Leads — the internal Doozer-sales CRM\n\n`includes/doozer-prospects.php`. Shipped v2.2.416-417. The strategic payoff of all the\ntracking: it turns postcards + claims + the leads-we-deliver into a ranked list of who is\nwarm enough to close on Doozer+. Jon's flywheel, made visible: they know us → we send them\nvalue (leads) → we make the right offer → free becomes Doozer+.\n\n## The awareness score (conversion readiness, 0-100)\n\n`businessDoozerAwareness($bizIdOrRow)` → score + component breakdown + status. Weights live in\n`doozerAwarenessWeights()` (one place to tune):\n\n| signal | pts | why |\n|---|---|---|\n| claimed the listing (`admin_email` set) | +40 | they acted, they know us — biggest |\n| scanned our postcard (`thanksio_events` scan) | +18 | engaged with our mail |\n| postcard delivered | +6 | mail physically reached them |\n| each postcard sent (`thanksio_sends`) | +3 (cap 9) | touches |\n| **each lead WE delivered** (`nbmn_lead_requests.routed_to_business_id`) | +12 (cap 40) | we give value — the strongest \"we have something to offer\" |\n| live Doozer site | +4 | inventory exists |\n\nStatus: paying owner (`businessIsPremiumOwned`) → `customer` (not a lead — a save/expand\ntarget). Else `hot` (≥55) / `warm` (≥25) / `cold`.\n\n## Hot Leads list + admin\n\n`doozerHotLeads($opts)` — candidate set = businesses we've TOUCHED (mailed OR delivered a lead\nOR claimed); never-touched businesses are not leads. Scored, ranked hottest first, customers\nexcluded by default. `$opts`: niche, state, limit, min_score, include_customers. Admin at\n**Intelligence → Hot Leads (Doozer+)** (`admin-prospects.php`): score bars, the \"why\"\nbreakdown, and Postcard / Manage quick actions. CLI `dz prospects [do=hot|score b=]`.\n\n## Next best action + channel (v2.2.418)\n\n`doozerProspectAction($row)` returns action + channel + urgency (now|soon|later) + reason.\nThe channel rule (Jon): getting leads + email → **email** the claim invite; getting leads +\n**NO email** → **mail a postcard STAT** (these sort to the top — leads with no inbox = money on\nthe table); mailed already + still no email → **call** the phone; claimed + free → Doozer+ pitch\n(email else mail). **SMS is OUT (regulatory).** Facebook Messenger via official page = future.\n`doozerHotLeads` sorts urgency-first. `doozerProjectedClaim($row)` = projected claim % (heuristic\nuntil real outcomes; getting-leads ×3.5, scanned ×2 over a ~4% cold baseline) — sharpens as\nclaim/convert rates by niche+market accrue (feed from the postcard Format-performance panel).\n\n## The LeadBuilder pipe (v2.2.418)\n\n`doozerProspectsPipeToLeadBuilder()` (admin \"Sync to LeadBuilder\"; `dz prospects do=pipe`)\nupserts each prospect into **`lb_leads`** (in the LeadBuilder DB via `nbmnLeadGetDb`), source\n`doozer_internal`, intent `doozer_plus_prospect`, under a synthetic \"Doozer Internal Sales\"\n`lb_site`, one `lb_visitor` per business (reuses `nbmnLeadEnsureLbSite`/`Visitor`). `score_factors`\ncarries `doozer_business_id`, awareness, projected %, signals, and next_action/channel/urgency.\nIdempotent (upsert by site+visitor+source). Internal prospects now live inside LeadBuilder proper.\n\n**Distinct from Machi** (`machi.md`): Machi = OUTBOUND NEED (\"who to mail next\"); this =\nCONVERSION READINESS + the exact next move. NEXT: campaign/niche/market response comparison to\nauto-weight targeting (\"mechanics claim 20% more → mail more mechanics\"); FB Messenger channel;\ncross-sell Keeper/agency to `customer`-status businesses.\n\nTies to [[project_monetization_plan]], [[the-observed-world]] CLAIM→EARN, the\n[[feedback_right_offer_right_audience]] rule, and [ai-postcards](ai-postcards.md) tracking." }, { "id": "indexnow", "title": "IndexNow (instant crawl notification)", "type": "System", "group": "systems", "description": "Push index-eligible Doozer URLs to Bing/Yandex the moment they cross the quality gate, so fresh and changed pages get crawled in hours instead of weeks. Bing-first hedge against the Google scaled-content classifier that cliffed elks.", "tags": [ "seo", "indexnow", "bing", "crawl", "sitemap", "quality-gate", "indexing" ], "path": "systems/indexnow.md", "links": [ "seo-cliff-recovery", "the-observed-world" ], "status": "", "generated": null, "verified": [], "stale_after": "", "sources": [], "body": "# IndexNow (instant crawl notification)\n\nIndexNow is a free \"push\" protocol: you notify participating search engines\n(Bing, Yandex, Seznam, Naver) that a URL is new or changed, and they crawl on\ndemand instead of waiting for a sitemap re-fetch. **Google does not consume\nIndexNow**, so this is a Bing-first play, and a deliberate hedge: elks.club\ncliffed on Google's scaled-content classifier\n([SEO cliff & recovery](../decisions/seo-cliff-recovery.md)), so diversifying the\ntraffic base onto Bing matters.\n\nShipped v2.2.359. `includes/indexnow.php`.\n\n## How ownership works across 2,400+ domains\n\nIndexNow verifies you own a URL by fetching a key file (`https:///.txt`)\n**on the same host as each submitted URL**. Doozer already serves `robots.txt`\ndynamically on every domain, so we do the same for the key file: `index.php`\nmatches `/<32-hex>.txt` and echoes the one shared key. That means a single key\n(`platform_settings.indexnow.key`, generated on first use) verifies the entire\nnetwork, with no per-domain key management. The route is on the sessionless path\nlist so it never takes a session lock.\n\nBecause each Doozer business site is its own host (e.g. `lodge.elks.club`),\nsubmissions are one host per request. Directory/root hosts with many URLs batch\ninto a single request (IndexNow allows one host, many URLs).\n\n## The load-bearing guardrail\n\nSubmit **only index-eligible URLs** — the exact sitemap rule:\n`domains.status='active' AND include_in_sitemap=1 AND\nbusinesses.ai_generated_content IS NOT NULL`. Never push skeletons, `noindex`, or\nthin pages. Pushing slop to a search engine re-teaches it that we emit slop,\nwhich is the precise mistake that hurt elks. This reuses the existing quality\nsignal rather than inventing a new one — enrich-then-index, same as the\n[observed-world flywheel](../decisions/the-observed-world.md).\n\n## Triggers (both async, via the `indexnow_submit` job)\n\n- **Content change:** `saveGeneratedContent()` (ai-content.php) enqueues after any\n write that leaves a business index-eligible. Covers fresh builds crossing the\n gate AND every regen (so a de-boilerplate fleet run doubles as a Bing recrawl\n signal, for free).\n- **Manual include:** the admin \"toggle sitemap\" handler enqueues when a domain is\n flipped INTO the sitemap. Removal is a no-op (IndexNow has no de-index).\n\n## Safety rails\n\nDaily cap (`indexnow.daily_cap`, default 2000), short-window dedup (don't\nre-hammer a URL pushed OK in the last hour), a self-creating `indexnow_submissions`\naudit table, and loud logging on any 4xx/5xx (the elks credit-outage lesson:\nnever swallow a provider error). Zero API cost.\n\n## Operating it (Dev API)\n\n`dz indexnow` — status (key, enabled, cap, sent today, recent rows).\n`dz indexnow test=` — force one submit (bypasses the switch) to prove the\npipe. `dz indexnow enable=1|0` — master switch. `dz indexnow rotate=1` —\nregenerate the key (invalidates the old key file). `dz indexnow run=backfill\nroot=` — queue every currently-eligible URL for a root, chunked (e.g. backfill\nelks.club to push the ~1,700 de-boilerplated pages at once).\n\nVerify with Bing Webmaster Tools → IndexNow, which shows submissions landing." }, { "id": "lead-capture", "title": "Lead Capture (the revenue pipeline)", "type": "System", "group": "systems", "description": "How a visitor's message or call becomes a routed, deliverable lead — the shared nbmn_lead_requests pipeline, auto-routing, no-email self-heal, and LeadBuilder handoff.", "tags": [ "leads", "monetization", "contact-form", "leadbuilder", "routing", "value" ], "path": "systems/lead-capture.md", "links": [ "the-value-model", "implicit-verification", "free-tier-render-gotchas" ], "status": "", "generated": null, "verified": [], "stale_after": "", "sources": [], "body": "# Lead Capture\n\nLeads are how Doozer turns free sites into revenue (see\n[the value model](../decisions/the-value-model.md)). There is ONE lead pipeline;\nevery surface feeds it.\n\n## The pipeline\n\n`nbmn_lead_requests` is the single table. A lead enters from:\n- **A business site's contact form** — `includes/contact-form.php`\n (`contactFormButton()` + `renderContactFormDialog()`), posting to\n `?e=nbmn_lead_request` with `lead_source=business_site` + `selected_business_id`.\n- **A NearByMeNow directory CTA** — the \"have a top-rated reach out\" form.\n- **Call / intent signals** — `includes/call-intent-categories.php`\n (`callIntentChipsForNiche()`) logs to `lead_intents` + bridges to LeadBuilder.\n\nFrom the table: **admin triage** (`includes/nbmn-lead-requests.php`) →\n**route-to-owner** (`nbmnLeadRouteToBusiness()`) → **LeadBuilder bridge**\n(`leadCaptureBridgeToLeadBuilder()`). Routing to an owner emails them when a\ncontact address is on file.\n\n## One business, one inbox (the canonical recipient)\n\n`businessLeadRecipientEmail($business)` (nbmn-lead-requests.php) is THE single\nplace lead-recipient precedence is decided: the **claimed owner** (`admin_email`,\nset when someone redeems a postcard code or matches by email) wins; the scraped\n`businesses.email` is only the fallback for an unclaimed listing. One business,\none inbox — every lead from anywhere in the ecosystem (business site, NBMN, calls,\nclouds) goes to that one email. Future agency/agent fan-out extends this one\nfunction. The redeem + claim pages state the promise to the owner explicitly\n(\"the email you claim with becomes where every lead arrives\"). See\n[[identity-and-auth]] (implicit verification: `admin_email` = the claim).\n\n## Auto-route + the no-email plan (load-bearing)\n\nA `business_site` lead with a `selected_business_id` **auto-routes on submit** —\nthe target is unambiguous (it's the site's own business). If the business has\n**no email**, the lead is not dropped: Doozer fires a priority `basic_enrichment`\nemail-discovery scrape (the [implicit-verification](../decisions/implicit-verification.md)\nself-healing backfill) and flags the lead `awaiting_email` to deliver once an\naddress lands. **A lead is never a dead end** — delivered if reachable, hunted for\na channel if not, and held meanwhile as a warm lead + an ownership hook. NBMN\ndirectory leads still go through manual triage (which business a directory lead\nbelongs to is a judgment call).\n\n## Spam + integrity\n\nreCAPTCHA v3 (`includes/recaptcha.php`, invisible/score-based, **fail-open** so a\nGoogle outage never drops a real lead) + a honeypot field + per-IP-hash rate\nlimiting. Keys live in `platform_settings` (secret-free in the graph).\n\n## The gotcha that made it work\n\n`getParam()` (`includes/api-endpoints.php`) read ONLY `$_GET` until v2.2.319, so\nevery `?e=` WRITE endpoint silently ignored POST-body params and the lead forms\ncaptured nothing. It now reads `$_GET` then falls back to `$_POST`. Any new write\nendpoint can accept a normal form POST. Filed under\n[render gotchas](free-tier-render-gotchas.md): the write \"succeeded,\" the row just\nnever arrived." }, { "id": "leadbuilder", "title": "LeadBuilder (the lead-intelligence platform)", "type": "System", "group": "systems", "description": "Where every captured lead, call intent, and cross-site referral flows to become revenue — the sibling product that turns Doozer traffic into qualified leads.", "tags": [ "leadbuilder", "leads", "monetization", "intelligence", "tracking", "value" ], "path": "systems/leadbuilder.md", "links": [ "lead-capture", "the-value-model", "shared-business-card", "the-network", "billing", "the-flywheel", "prospector" ], "status": "", "generated": null, "verified": [], "stale_after": "", "sources": [], "body": "# LeadBuilder\n\n`leadbuilder.io` is a BerrySmart sibling product: the **lead-intelligence\nplatform** that Doozer feeds. If [Lead Capture](lead-capture.md) is the plumbing,\nLeadBuilder is the destination and the intelligence layer — where a visitor's\naction on a business site becomes a qualified, attributable lead a business will\npay for. It is the primary way Doozer's traffic turns into revenue (see\n[the value model](../decisions/the-value-model.md)).\n\n## What flows in\n\nEvery demand signal on the network bridges to LeadBuilder:\n\n- **Leads** — contact-form and NBMN lead-requests, routed via\n `nbmnLeadRouteToBusiness()` and piped in by `leadCaptureBridgeToLeadBuilder()`.\n- **Call intent** — the category-aware Call popups (`lead_intents`) bridge here.\n- **Visitor events** — `renderLeadBuilderSnippet()` mounts a lightweight tracker on\n business + directory pages, recording sessions and events to the `lb_*` tables\n (`lb_users`, `lb_sessions`, `lb_events`, `lb_follows`).\n- **Cross-site referrals** — the [neighborhood direct links](shared-business-card.md)\n fire `sendBeacon` → the `track_network_referral` endpoint → a\n `click_network_referral` `lb_event` on the SOURCE site, so movement across the\n [network](the-network.md) is attributed, not lost.\n\n## Why it matters\n\nA free Doozer site creates presence; LeadBuilder captures the value that presence\ngenerates and makes it measurable and sellable. `lb_users.tier` also carries the\nentitlement that [Billing](billing.md) sells, so the same identity spans the free\nsite, the lead intelligence, and the paid tier. It is the revenue engine of\n[the flywheel](the-flywheel.md), and the reason \"we build a free site\" is a\nsustainable business rather than a cost center.\n\n## Google Search Console ingestion (the demand data)\n\nLeadBuilder also owns the network's **Google Search Console pipe** — the search\ndemand data that powers [Prospector](prospector.md)'s Cloud Radar and the\nmarketing signal miner. `includes/lb-gsc-client.php` is a dependency-free OAuth 2.0\n+ Search Analytics client. Operator connects GSC properties (Admin → LeadBuilder →\nGSC Properties); refresh tokens are stored encrypted in `lb_gsc_properties`.\n`lbGscSyncProperty($propertyId, $daysBack)` pulls query + page aggregates into\n`lb_gsc_query_daily` / `lb_gsc_page_daily`. GSC Search Analytics is **free** — no\nper-call cost.\n\n**Freshness is a background job.** `lbGscMaybeQueueRefresh()` runs from the\nindex.php shutdown tick (rate-limited 6h) and enqueues a per-property `gsc_refresh`\njob when a property's `last_synced_at` goes stale (>20h); the job dispatcher runs\nthe sync. Built v2.2.364 — before that the scheduler was referenced in a comment\nbut never existed, so ingestion silently died after one manual sync (May 2026) and\nCloud Radar ranked on a frozen snapshot.\n\n**Two durable gotchas (v2.2.364):** (1) refresh tokens are encrypted with\n`ENCRYPTION_KEY`; a key rotation breaks decryption unless the decrypt tries the\nlegacy keys — `lbGscDecryptTokenEx()` now uses `doozerLegacyEncryptionKeys()` +\nself-heals (re-encrypts with the current key). (2) If the Google OAuth **consent\nscreen is in \"Testing\" mode, refresh tokens expire after 7 days** → `invalid_grant`\n→ dead pipe. Fix: publish the consent screen to production + reconnect the\nproperties. Dev API `gsc` (status / `sync` / `scan`) drives + diagnoses it all." }, { "id": "livemusictonight", "title": "Live Music Tonight (livemusictonight.com)", "type": "System", "group": "systems", "description": "A demand-sensing live-music discovery directory built on the Vertical Directory engine, fed by the Ticketmaster/Marquee feed, that captures visitor interest as a graph to decide which venue sites to build next.", "tags": [ "vertical-directory", "events", "music", "marquee", "ticketmaster", "interest-graph", "prospector" ], "path": "systems/livemusictonight.md", "links": [ "vertical-directory", "prospector", "cloud-factory", "the-flywheel", "shared-business-card", "gathering" ], "status": "", "generated": null, "verified": [], "stale_after": "", "sources": [], "body": "# Live Music Tonight\n\n`livemusictonight.com` is a [Vertical Directory](vertical-directory.md) (one host row routed\nby `includes/vd-router.php` → `includes/vertical-directory.php`). It is not a bespoke page —\nit reuses the VD engine. It started empty because `vdFetchEvents()` read the unpopulated\n`dynamic_section_cache`; it now sources real shows.\n\n## Data resolution (here-and-now first)\n\nLive music is a NOW thing, so the homepage leads with **location + Tonight** and lets the\nvisitor expand outward in time and space.\n\n- **Located** (explicit `?lat&lng` from the geolocate button, or approximate from\n Cloudflare `CF-IPLatitude/Longitude`): live Ticketmaster geo feed via\n `marqueeTmFetch()` (gained `latlong`/`radius`/`unit`/`endDateTime`/`sort`), closest\n first. If nothing falls in the radius/window, an empty state nudges widening — it never\n silently dumps far-away national events on a located visitor.\n- **No location**: stored `marquee_events`, then a live national fallback so the page is\n never blank. This is the browse mode where search/filter belongs (future).\n- Radius filter: 5 / 10 / 25 / 50 / 100 miles, **default 5**. Auto-requests precise\n location on first load (remembers a denial via sessionStorage, no nagging).\n\n## Time windows (30-day horizon)\n\n`vdWindowEnd()` hard-caps everything at +30 days (no stray next-year listings). `Tonight`\nis here-and-now; `This Week` / `This Month` are calendar-bounded; `Next 7 Days` /\n`Next 30 Days` roll forward from today regardless of the date. The nav exposes the rolling\noptions via dropdowns on This Week / This Month.\n\n## The interest graph (the point)\n\nEvery **Interested** and **Tickets** click records a demand signal to `lmt_interest`\n(`?ajax=lmt_interest`, ip-hash rate-limited) keyed to **venue identity** + genre + area.\nThis is OUR derived demand signal, not a mirror of Ticketmaster's catalog (ToS-clean).\nAdmin → Marquee → \"Live Music Demand\" ranks venues by interest (interested×3 + ticket×5)\nand hands a venue to the build flow. So real demand decides which venue sites\n[Prospector](../glossary/prospector.md) and the [Cloud Factory](cloud-factory.md) build\nnext — the [flywheel](the-flywheel.md) applied to events.\n\n## Ecosystem ties\n\n- Cross-ecosystem identity: the [user avatar](shared-business-card.md) renders in the VD\n header (magic-link sign-in), so Interested can tie to a real person.\n- Photos: TM event images render as card thumbnails (music-note SVG placeholder otherwise).\n- Icons follow the house rule — crafted inline SVGs, never emoji/clipart.\n- **Venue cross-link by ID:** Marquee stamps Ticketmaster's `tm_venue_id` onto the\n `businesses` row when it builds a venue site (`marqueeStampVenueId`), so `_vdLinkVenues`\n links a live event to its Doozer site deterministically (`businesses.tm_venue_id =\n event.tm_venue_id`) instead of fuzzy name matching. This is the durable handle a venue's\n own business site can use to point back at LMT or any vertical directory.\n- **Interested on business sites:** each event on a venue's Doozer site (rendered by\n `renderBusinessEventsSection`) carries an Interested button (internal bookmark via\n `lmt_interest`) beside Tickets and + Calendar — the network keeps the save instead of\n pushing people to an external calendar.\n\n## Marquee is venue discovery, not an event log\n\nThe Marquee admin (`marqueeRecentVenues`) surfaces ONE row per distinct venue (keyed by\n`tm_venue_id`, else name+city+state), NEW venues (no Doozer site) first, built ones marked.\nThe product is *finding businesses to build* through the live event feed — not listing events.\nBuild acts on a representative event; the rest of the venue's shows become its site's calendar.\n\n- Future: an \"add all to calendar\" iCal feed on my.doozer.cloud for a user's saved events +\n gatherings; clicking a show could spin up a [Gathering](../glossary/gathering.md) on GoHe.re\n (gated on the gatherings surfaces); non-ticketed/community shows union into the same feed." }, { "id": "magellan-and-feeds", "title": "Magellan and the feed pond — bound IDs turn sites into living entities", "type": "System", "group": "systems", "description": "The business_id_map spine (built v2.2.549) plus the feed adapters that hang off it. A bound external ID is what lets a generated page carry current, authoritative, self-maintained content instead of static prose.", "tags": [ "magellan", "feeds", "identity", "calendar", "elks", "accuracy", "strategy" ], "path": "systems/magellan-and-feeds.md", "links": [ "magellan-id-mapping" ], "status": "", "generated": null, "verified": [], "stale_after": "", "sources": [], "body": "# Magellan and the feed pond\n\n**The operator direction (Aug 21 2026):** \"Cross link as much as we can and turn feeds,\nsites, and other directories into data feeds. Doozer sites need to be living entities.\"\n\n## The spine (BUILT — `includes/magellan.php`, v2.2.549)\n\n`business_id_map (business_id, service, external_id, source, confidence, verified_at)`,\nunique per `(business_id, service)`, reverse-indexed on `(service, external_id)`. This is\nthe table specified in [magellan-id-mapping](../decisions/magellan-id-mapping.md) in June\n2026 and finally built. `magellanBind/Id/Find/All/BackfillHot/Stats`; `dz magellan`.\n\nLive coverage: **google 3,632 · elks_org 1,704 · gcal (growing) · ticketmaster 101.**\n\nThe hot columns (`businesses.google_place_id`, `businesses.tm_venue_id`) are NOT touched;\n`magellanBackfillHot()` copies them IN so both views agree while callers migrate.\n\n**The rule stays: join by ID, never by name+city+state.** Name matching guesses,\nduplicates, and fails silently.\n\n## Why a bound ID matters (the actual point)\n\nA generated page describing a business is one of thousands and gets skipped. A page\ncarrying **what is on tonight** is the only page answering that question. A bound ID is\nwhat makes the second thing possible, and it is also an accuracy engine: every feed is a\nsecond opinion on the facts.\n\n## Feed adapters\n\n### `gcal` — public Google Calendar (`includes/feed-gcal.php`, GENERIC)\n\nA public Google Calendar exposes iCal at a predictable URL with **no key and no quota**.\nAny page embedding one names a live, self-maintained event feed.\n\n