🔧 Reference

Spark — Listing Showcase Builder

1 source Updated Sun Apr 19 2026 19:00:00 GMT-0500 (Central Daylight Time) Internal
toolsparkreferencetool-inventory

Summary

Spark — Listing Showcase Builder — regenerated from canonical/guides/tools/spark.md. Do not hand-edit this page — update the canonical file and re-project. Status: live. Primary domain: spark.stoicagent.com. Pipeline role: entry point — listing marketing pipeline.

Content

Purpose

MediaExperts link (or MLS number) in, branded per-listing showcase page out in ~60 seconds. Builds the first marketing asset for every listing we take. Entry point of the listing marketing pipeline.

Current state

  • Status: Live, flagged v1.0 BETA for agent messaging purposes
  • Replaces: Curaytor listing landing pages (partial — Curaytor stays active until full Hermes pipeline is proven)
  • Pipeline position: Entry point → feeds Lyra short link → feeds Hermes inventory → Slack premarket channel post → FUB lead routing pre-wired

What a build produces (as of 2026-04-20)

  1. Branded Netlify page on the 1205 River Birch Dr golden template (Telegraf + Inter, Cobalt/Coral palette, drive times, school zones, remarks)
  2. Lyra short link at l.getrealstl.com/[address-slug]
  3. FUB test lead fired and tagged with the property address so real leads route automatically to the listing agent
  4. Hermes inventory push (auto-populates Listing Promo mode chips — see Hermes integration section)
  5. Direct Slack DM to Fred + the listing agent with the live URL, short link, and FUB tag
  6. Slack channel post to #premarket-listings (C07EDN6AL83) with address, beds/baths/SF, key features, listing agent, status + active date, short link, and a pre-filled recommended sphere-marketing text

Where it lives

  • Code: Tools/Spark/server-hardened/ — main build server (showcase_server.py, Flask)
  • GitHub: venterminator-web/artemis-spark-server
  • Deployed (frontend form): spark.stoicagent.com → Netlify artemis-showcase-builder.netlify.app
  • Deployed (backend build service): Droplet 192.241.142.56, systemd unit showcase-builder.service, port 5050
  • Skill: .claude/skills/showcase-page/ (gold standard template — 1205 River Birch Dr)
  • User guide: Training & Playbooks/Artemis Asset Library/Spark - Agent User Guide v1.0.pdf (generated from Brand Assets/spark-user-guide-v1.html via Playwright)

Integrations

  • MediaExperts / MLS Grid (input) — agent provides link or MLS#, Spark scrapes/queries
  • MARIS PostgreSQL (live at 192.241.142.56) — listing details, agent, school district, remarks, coords
  • Aryeo — photos, floor plans, 3D tours when Showcase URL provided
  • MLS Grid API — photo fallback when Aryeo is missing
  • Lyra — auto-creates short URL at l.getrealstl.com/[slug]; every Spark page goes through Lyra for attribution + analytics
  • Follow Up Boss — fires a test lead at build so the property tag is registered; real leads from the page route to the listing agent automatically
  • Hermes — pushes the new listing into listings Blob store via the listings-intake function; enables Listing Promo campaign builds
  • Slack — DM to Fred + listing agent (always); channel post to #premarket-listings (since 2026-04-20) with recommended sphere text

Hermes integration (shipped 2026-04-20)

Spark auto-populates Hermes inventory on every successful build. No manual handoff.

  • Intake URL: https://artemis-social-poster.netlify.app/.netlify/functions/listings-intake
  • Auth: X-Spark-Secret header, shared secret SPARK_INTAKE_SECRET set on both Hermes Netlify env + Spark droplet systemd unit
  • Payload: sparkUrl, lyraUrl, address, city, status, price, beds, baths, sqft, photoCount
  • Failure model: non-fatal — a Hermes outage never blocks a Spark build
  • Secret rotation: must update both sides; Netlify Functions v2 requires a real redeploy (not restoreSiteDeploy) to pick up new env. Full procedure in memory spark_hermes_integration.md.

Today Hermes ingests these for manual campaign deployment. Phase 3 of Hermes automates the full campaign build off the inventory.

Known-issue history

  • 2026-04-20 — YN text-parse bug. BasementYN and PoolPrivateYN are stored as TEXT in MARIS ("True"/"False"/"Yes"/"No"/NULL), not boolean. Python bool("False") is True, which was silently adding "Finished Basement" / "Pool" badges to every listing with a populated YN field. Shipped 421 Wolf St with a false "Finished Basement" hero badge. Fixed via _parse_yn() helper in both showcase_server.py and build_showcase.py; added BelowGradeFinishedArea to the SELECT so the badge can distinguish "Finished Basement" vs plain "Basement". Rule for future: never use Python bool() on any MARIS text column.
  • 2026-04-20 — Hero badge age/historic framing. Never use "Built YYYY" on old-but-not-historic homes. Reserve historic framing for true historic properties (district designation, architectural pedigree). Prefer "Recently Remodeled" / feature badges. Memory: feedback_spark_hero_badge.md.

Typical development touchpoints

  • Photo/media reliability → MLS Grid $expand=Media fetch path
  • Floor plan/3D support → Aryeo API
  • Data quality → ATTOM + Regrid pipeline
  • Branding/fonts → Brand Assets/golden-document-template.html + .claude/skills/showcase-page/golden-template.html
  • Droplet secrets → /etc/systemd/system/showcase-builder.service
  • Hermes integration env vars → HERMES_INTAKE_URL + SPARK_INTAKE_SECRET in same systemd unit

Deploy

bash Tools/Spark/server-hardened/deploy.sh

Droplet does git fetch origin main && git reset --hard origin/main && systemctl restart showcase-builder. Health check endpoint: GET /health → {"status":"ok",...}.

Related

  • Inventory row: canonical/business-state/tool-stack-inventory.md → "Spark"
  • Hermes tool guide: canonical/guides/tools/hermes.md
  • Lyra tool guide: canonical/guides/tools/lyra.md
  • Gold standard skill: .claude/skills/showcase-page/ (vault) or ~/.claude/skills/showcase-page/ (Claude Code)
  • Archived predecessors (DO NOT USE): landing-page-with-attom, landing-page-with-multi-source-data, showcase-builder (all superseded 2026-04-11)
  • Memory: Gold Standard Landing Page, Spark Droplet Secrets, Spark Hermes Integration, Spark Hero Badge Feedback

Active WIP location

working/drafts/tools/spark/ (create as needed during active development)

Open questions / gaps

  • Hermes intake endpoint lives on feature/listing-promo-mode branch, not main. Current prod Hermes deploy is from that feature branch. Merging to main is part of the broader Listing Promo mode ship.
  • Market-take line in recommended sphere text is a conservative default. Could evolve to pull live inventory stats from MARIS/Prometheus for city-specific timing lines. Not urgent — current default is defensible.