Build a 50-State Policy Signal Room with Replit and Synorb

Build a production-quality Replit app called "Statehouse Signal" — a 50-state policy radar powered by Synorb Streams. CONTEXT AND AHA MOMENT This must feel useful on the first live load, not like a generic feed template. A policy, public-affairs, newsroom, or partnerships user should be able to answer: What changed in the states I care about, which issues are moving, what is the primary source, and what should I inspect next? The product should visibly connect a Synorb Stream to cited Manifests, a human Brief, and a machine-readable Signal. COLLABORATIVE BUILD LOOP — MANDATORY Do not silently build the entire app in one pass. Guide the user through these checkpoints, ask one compact set of questions at a time, and wait for their answer before continuing. Recommend one option at every checkpoint. If the user says "choose for me", use the recommended defaults; never re-ask a settled choice. 1. Before coding, ask who the primary user is, which initial states/issues matter, and which starting experience they want: Map-first Command Center (recommended), split Map + Evidence Feed, or focused Single-State Workspace. In the same compact checkpoint, scope the visual and image preferences required by the Visual Asset Workflow below. 2. After MCP discovery, show the exact candidate Stream names, 17-digit string IDs, source-channel types, and available date window. Ask the user to confirm or adjust this live scope before persisting the state-to-stream configuration. 3. After the first working preview with real Synorb data, ask the user to choose information density (Executive, Balanced recommended, or Analyst-dense), prioritize up to three functions—window comparison, saved watches, review queue, exports, scheduled refresh, or Slack/email alerts—and approve one of the three visual candidates required below. Apply the choices together and show the revised preview. 4. Before deployment, ask whether the app is a private prototype, authenticated team tool (recommended), or public showcase, and confirm refresh cadence and delivery channels. Then run acceptance tests and present one concise build receipt listing product choices, visual choices, Streams, filters, routes, image provenance status, and deployment shape. SYNORB ACCESS CHECKPOINT — ASK AND WAIT Before any Synorb discovery call, ask the user to choose one option: A. Use my existing Synorb credentials. B. Get free Synorb credentials (recommended for a new user). For A, open Replit Secrets and ask the user to enter SYNORB_MCP_TOKEN, SYNORB_API_KEY, and SYNORB_SECRET there. Never ask them to paste secret values into chat, source code, a public environment variable, logs, or the database. For B, only after the user explicitly selects it, make exactly one GET request to https://synorb.com/connect from a one-time server-side setup task. Parse credentials.mcp_token, credentials.api_key, and credentials.api_secret without printing the response body. Store them directly as SYNORB_MCP_TOKEN, SYNORB_API_KEY, and SYNORB_SECRET in Replit Secrets; the API secret is shown only once. Never commit, render, log, or persist the raw values elsewhere. If Replit requires user confirmation to save Secrets or add the integration, ask for that confirmation without displaying the values. Use the MCP token with the Core server https://mcp.synorb.com/mcp and an Authorization Bearer header. Use the REST key and secret only as api-key and secret headers from server code. Validate MCP with synorb-profile and validate REST with GET https://api.synorb.com/account. If either check fails, stop at a credential-repair state. If the free-credential request returns no credentials or a 429, do not retry automatically; offer existing credentials or the returned retry guidance. BUILD-TIME DATA DISCOVERY WITH SYNORB MCP Use the connected Synorb MCP server before writing the feed implementation. 1. Call synorb-profile first. Read date_window, freshness, and quota state. Never request dates earlier than earliest_allowed. 2. Unless the user chooses different states, recommend a live demo scope of Delaware Legislature "17806683619855939", Michigan Legislature "17806683645237574", New Hampshire Legislature "17806683656669676", Oregon Legislature "17806683670592874", and Texas Legislature "17806683681409101". Verify every seed with synorb-details before use; IDs are string canaries, not permission to skip live validation. Then call synorb-stream-search with the exact query "state legislature", home_domain "society-law-government", include_details true, and page_size 20; paginate when coverage has more results. 3. Keep every Stream, source-channel, tag, and Manifest ID as the exact JSON string returned by Synorb. Never coerce a 17-digit ID to a JavaScript number. 4. Accept a legislature Stream only when its exact title is {State} Legislature and its verified source channels are bill-grade state surfaces, normally source_class "legislature" and evidence_type "bill_text". Keep {State} State Executive as a separate optional scope for governor actions; never silently mix it into the legislature mapping. Batch the selected IDs through synorb-details and build state-to-stream and state-to-source-channel receipts. Exclude Congress, federal agencies, federal courts, publishers, and generic commentary. 5. Pull a build-time sample with synorb-manifests using the selected stream_ids, a 30-day window inside the profile limits, compact true, page_size 12, target_count 12, source_class "legislature", evidence_type "bill_text", and topic tag_names such as "artificial intelligence", "data centers", and "energy" with tag_logic "or". Treat mode "orient" or "count" as preflight only; do not present those samples as exhaustive. Preserve quota_header, coverage.status, citations, and recommended_next_call in the build notes. 6. If MCP is not connected, still scaffold the product and show a precise setup state. Do not invent Stream IDs, sources, citations, or live stories. RUNTIME SYNORB API CONTRACT Store SYNORB_API_KEY and SYNORB_SECRET in Replit Secrets and call Synorb only from server code using api-key and secret request headers. - Create POST /api/feed. Its validated inputs are stateCodes, tagNames, publishedDateFrom, publishedDateTo, storyType, significance, page, and pageSize. - Map stateCodes to the verified Stream ID strings stored in a server-only config or database table. - Call POST https://api.synorb.com/streams/query with only supported fields: stream_ids, story_type ("briefs" or "signals"), published_date_from, published_date_to, tag_names, significance, media_format, page, and page_size. - Do not send cursor, query, mode, tag_logic, target_count, beacon_id, source_class, evidence_type, or MCP-only coverage fields to /streams/query. - POST /streams/query returns { data, usage } and flat rows under data.briefs[] or data.signals[]. Normalize the selected array; read headline, summary, significance, source_url, and dates from each flat row. Never expect data.manifests[] from this endpoint and never fabricate a citation. - Load more increments the zero-based page. Cache identical server requests for 10 minutes and include cacheAgeSeconds. - Add a server-only Stream detail route using GET /streams/{id} so the UI can show verified Stream metadata and source-channel receipts without exposing credentials. - Surface usage from the REST envelope. REST does not return MCP quota_header, coverage, or citations arrays; derive the citation only from each row's source_url and label empty results with the exact states, tags, and date window searched. REPLIT-NATIVE PRODUCT - Use Replit Auth so users can save private watch scopes. - Use Replit Database with tables for users, stream_catalog, watch_scopes, cached_feed_items, review_state, refresh_runs, and delivery_log. Use stable string IDs and unique constraints for idempotency. - Build an elegant responsive US map plus an accessible state-list fallback. Color states by new activity, not raw lifetime volume. - Add state and region selection, issue chips, significance, 24h / 7d / 30d / custom date controls, Brief / Signal toggle, Latest / Rising / Reviewed tabs, and a compare-to-previous-window switch. - Each result card must show headline, concise summary, state, issue tags, significance, published time, Stream name, source name, and a prominent "Open primary source" link. Add a collapsible "Synorb receipt" with Stream ID, source channel, request window, cache age, and returned row ID. - Create a right-side "What changed" panel that compares the selected window with the immediately preceding equal-length window using cached results. Explain the delta only from returned data. - Add polished loading skeletons, retry, stale-cache, auth, setup, zero-results, partial build-time coverage, and API error states. Never replace live failure with mock stories. - Use a server-capable Autoscale Deployment for the web app; this is not a Static Deployment. - Create a separate idempotent refresh command suitable for a Replit Scheduled Deployment. It should refresh saved scopes, persist new stable IDs, and never resend an already delivered item. VISUAL DIRECTION Make it feel like a modern policy operations room: crisp editorial typography, restrained navy/ink palette, one electric signal color, dense but calm information design, excellent mobile behavior, keyboard navigation, and subtle motion only when state changes. Avoid generic gradient cards and stock dashboard chrome. ACCEPTANCE TESTS 1. No Synorb secret or raw credential appears in browser code, HTML, logs, or API responses. 2. All Synorb IDs remain strings end to end. 3. Changing states, tags, dates, significance, story type, or page changes the exact server request. 4. Brief and Signal response shapes both render. 5. Every displayed fact has the returned source_url; no invented URLs or fallback copy. 6. Empty, thin, stale, rate-limit, auth, and quota-adjacent states are explicit and useful. 7. Include a README with setup from curl -s https://synorb.com/connect, how to add Synorb as a custom MCP server in Replit Integrations, required Replit Secrets, database schema, Autoscale publishing, Scheduled Deployment command, and a short demo script that reaches the aha moment in under two minutes. VISUAL ASSET WORKFLOW — INTEGRATED WITH THE BUILD LOOP Treat the product shell, data visualization, source-derived media, and generated imagery as one reviewed design system, not a decorative afterthought or a separate questionnaire. 1. At the first product checkpoint, offer two paths: use the recommended visual preset, or customize. Ask the user to choose or delegate the image approach - source or publisher artwork, editorial photography, cinematic generated imagery, data-led illustration, abstract visual system, or minimal imagery - plus restrained, balanced, or immersive prominence, brand colors and assets, and subjects, symbols, colors, cliches, people, or styles to avoid. Recommend data-led cartographic illustration in a modern policy-operations style with balanced, data-first imagery: one hero, truthful map treatments, and restrained state and empty-state accents. Summarize the answer as a Visual Direction Receipt and wait for confirmation. 2. Create a compact asset plan limited to visuals that improve comprehension or delight: a map-forward hero, map and regional textures, issue-category accents, official-document previews, empty states, and social-preview artwork. Label every planned asset as source-derived, data-derived, generated decorative, user-provided, or branded fallback. Never let decoration compete with live Synorb evidence or citations. 3. Add an app-owned optional visual record to normalized content types: image_url, image_alt, image_source_url, image_credit, image_kind, rights_status, width, and height. Do not assume Synorb REST returns these fields. Keep the visual resolver separate from the cited Brief and Signal adapters so a missing or broken image can never remove, alter, or delay the factual row. 4. Resolve visuals in this order: a permitted visual explicitly returned with the source object; permitted official artwork or metadata from the exact canonical source; a user-provided licensed asset; a user-approved generated decorative asset; then a polished non-photographic fallback. A narrow server-side visual-metadata lookup may read canonical RSS or Atom artwork, Open Graph or Twitter image metadata, or the first page of the exact cited PDF. It must not scrape article text, invent content, bypass access controls, or substitute another content provider. Cache only when source terms permit it. 5. Derive map color, counts, charts, and state activity only from returned Synorb data. A cited official bill or legislative PDF may receive a first-page document thumbnail when permitted. Never use generated art as a map value, bill preview, or factual state signal. Preserve the exact image source URL and credit separately from the Manifest source_url. Do not imply that a source-derived image is itself Synorb evidence unless Synorb returned it as part of the source object. 6. Use a reference image only when it is user-owned, verified CC0/public domain, or licensed for commercial use and modification. Record its URL, creator, and license. Reject editorial-only, non-commercial, no-derivatives, unidentified, or ambiguous rights. Appearance in web search is not permission. Do not claim that applying a filter makes a source image proprietary or removes its license obligations. Trademarks, privacy, and publicity rights may still apply. 7. Before generating a full decorative asset family, create three meaningfully different low-cost candidates for the highest-impact generated surface, place them in the real-data preview, and ask the user to select one, combine specified qualities, request another direction, or continue without generated imagery. Wait for approval before generating the complete asset family. Never request a replica of a copyrighted image, branded character or logo, unapproved real-person likeness, or the signature style of a named living artist. 8. Generated visuals are clearly decorative. Never present generated art as primary-source evidence, a factual visualization of Synorb data, a document preview, or a depiction of a returned event or claim. Save the approved direction, selections, revisions, crop decisions, and layout treatment without promising exclusive copyright or proprietary rights. 9. Write docs/image-provenance.json for every shipped visual with filename or remote URL, product location, image_kind, creation or resolution method, provider, generation or retrieval date, creative brief when applicable, human selections and edits, image_source_url, creator, license, rights_status, and crop information. Never put credentials in this file. 10. Ship responsive AVIF/WebP assets when locally transformed, with an appropriate fallback, stable aspect ratios, useful alt text, mobile and desktop crops, lazy loading below the fold, and no important text baked into images. Exercise a real visual, missing visual, broken visual, fallback, light and dark themes, reduced motion, mobile, tablet, and desktop. Include the final asset list and image provenance status in the build receipt.

curl -s https://synorb.com/connect