chIRpChat Website Plan

Research — non-normative

This page is synced from the repo’s docs/research/ tree: exploratory design work, forward-looking plans, or historical analysis. It may describe behavior that is not built or that shipped differently. The normative spec lives in the other docs sections.

Status of this document: forward-looking, non-normative. It plans a public marketing/docs website for chIRpChat to be built in a new, separate repository deployed on Cloudflare Pages. Nothing in this document changes lrc code or normative docs/. Grounded in docs/COMPARISON.md, docs/ENGINEERING_DEEP_DIVE.md, README.md, and the docs/research/ tree — no invented features. Where the docs are silent (e.g. COMPARISON_THESIS.md does not currently exist in the repo), this plan relies on COMPARISON.md and ENGINEERING_DEEP_DIVE.md §13 instead, which cover the same ground in more depth.

---

1. Competitor teardown

1.1 Meshtastic (meshtastic.org)

Nav structure (top nav): Logo/Home · Docs · Blog · Downloads · Flasher · language selector · search · Donate · GitHub. Header and footer both carry a heavy social bar: Discord, X, Facebook, Instagram, YouTube, Reddit, Bluesky, Mastodon, Telegram.

Landing page, top to bottom:

1. Hero — headline “Off-Grid Communication For Everyone”; subhead: “An open source, off-grid, decentralized mesh network built to run on affordable, low-power devices. No cell towers. No internet. Just pure peer-to-peer connectivity.” Two CTAs: Get Started / Read the Docs.
2. Stats band — device count, contributor count, “26 LoRa regions,” “39 languages,” plus an interactive demo widget.
3. Key features — three cards: Long Range (LoRa), Encrypted (AES-256), No Infrastructure.
4. “Get Connected” — four platform tiles with CTAs: Apple app, Android app, Web client, Python CLI/SDK.
5. Sponsor/partner logo wall.
6. Footer — social links, copyright, trademark notice, legal.

Docs IA (top-level sidebar sections, in order): About (Introduction, Overview, Contributing, FAQs) → Getting Started → Configuration → Hardware → Software → MeshtasticD → Community → Development → Legal → Glossary of Terms.

Getting-started flow (new user path): identify hardware class (ESP32 / nRF52 / RP2040-RP2350) among partner/backer/community-supported devices → verify the USB cable actually carries data (an explicit warning: “Some cables only provide charging, verify that your cable is also capable of transferring data before proceeding”) → install serial drivers (split by chip family) → flash firmware (split by chip family) → Initial Configuration: set region (frequency legality) → connect app. The overview page notably stops short of app installation and “joining a mesh” — that’s implicit / left to the app’s own onboarding.

Web flasher (flasher.meshtastic.org): official, browser-based, built on the Web Serial API plus a JS port of Espressif’s esptool (their own open-source meshtastic/web-flasher repo, not a third-party tool). Chrome/ Edge only (Web Serial isn’t in Safari/Firefox). Auto-downloads latest firmware from the official release feed; includes a serial monitor for post-flash debugging. No installed software, no Python, no esptool.py required — this is the strongest single piece of Meshtastic’s onboarding.

Blog: active and technical — recent posts mix routing-algorithm deep dives (“Demystifying ROUTER_LATE,” “Zero-Cost Hops for Favorite Routers”), release previews (2.6/2.7 UI and routing changes), community/event coverage (DEF CON deployment), and practical how-tos (repurposing mining rigs as nodes). This is a genuine technical blog, not just release notes — worth imitating in tone.

Strengths to note:

• The web flasher is best-in-class: zero-install, one-click, Chrome-only friction is the only cost.
• Docs IA cleanly separates “how do I use this” (Getting Started/ Configuration) from “how does this work” (Development) from “what hardware” (Hardware) — a pattern worth mirroring.
• Blog builds genuine technical credibility with the audience that will actually evaluate a competing protocol.
• Stats band (“26 regions,” “39 languages,” device/contributor counts) signals maturity fast, without saying anything about the protocol itself.

Weaknesses chIRpChat’s site can beat:

• No honest “why us” / comparison page. Meshtastic’s site never positions itself against MeshCore or anything else — a visitor comparing networks has to leave the site. chIRpChat should own this territory with a direct, sourced comparison page (we already have one: COMPARISON.md).
• The onboarding flow buries the actual “first message” moment. Getting Started stops at “connect and configure” — there’s no single page that says “you are now talking to another node, here’s what that looks like.” New users have to infer success.
• The four-app grid (iOS/Android/Web/Python) has no default recommendation — a first-time visitor has to pick a client with no guidance, which is a subtle but real “which do I want” tax. chIRpChat’s answer to “which client” is trivially “the one you already have” — a structural onboarding win the site should lead with.
• The docs are Docusaurus-standard but generic — no code-level protocol spec is exposed at the marketing-docs layer (the wire format lives only in firmware source). chIRpChat’s protocol docs (PROTOCOL.md) are already normative and detailed; publishing them raises credibility with the hobbyist/embedded audience that reads Meshtastic’s blog.
• No performance/scaling honesty. Nothing on the site says what breaks at scale (flood collapse, single-preset-per-mesh ceilings). chIRpChat’s ENGINEERING_DEEP_DIVE.md §9 (“why not a million users”) is unusually candid — that candor itself is marketable to a technical audience burned by vague marketing claims elsewhere.

1.2 MeshCore (meshcore.co.uk)

Nav structure (top nav): Get Started · Get Devices · Network Map · User Guides. Secondary: Features · Videos · “How to activate MeshOS” · Developer Docs (→ GitHub). Utility links: Blog · Store (store.meshcore.co.uk) · “Set Up Your Device” (→ /configurator/) · “Launch Web App” (→ app.meshcore.nz, a separate domain).

Footer nav: Product (Set Up Device, Apps, Devices, Store) · Resources (Blog, User Guide, Videos, Network Map, MeshOS Activation, About) · Community (Developer Docs, YouTube, Contact).

Landing page, top to bottom:

1. Hero — headline “Connect Without The Internet”; subhead: “Secure, decentralised mesh radio platform powered by LoRa. Communicate across kilometres — no towers, no subscriptions, no single point of failure.” Three CTAs: Set Up Device / Get App / Standalone Devices.
2. Social-proof stats band — “30K+ Users,” “80+ Countries,” “50+ Supported Devices.”
3. “Built for Resilience” feature grid — Fully Decentralised, End-to-End Encrypted, Extreme Range, Multi-Platform Apps, Flash in Seconds, IoT Ready.
4. “Where MeshCore Shines” use-case grid — Emergency Response, Outdoor Adventures, Events & Festivals, Private & Secure Communications.
5. “Three Steps. That’s It” — Get Device → Set Up → Start Messaging.
6. Apps section — two apps side by side: MeshOS (official, multi- platform, standalone-device-capable) vs. MeshCore by Liam Cottle (community-built companion app), with screenshots/download links for each.
7. Hardware gallery, three device classes: Companion Nodes (need a phone), Repeater Nodes (range extension only), Standalone Nodes (MeshOS, phone-free).
8. “Join the Mesh” community CTA.

Commercial/free split: the protocol, firmware, and both apps (MeshCore-by-Liam-Cottle and MeshOS) are free/open; the business is hardware — sold through their own store plus Amazon and manufacturer retailers (Heltec, LilyGo, SeeedStudio, RAK Wireless, Elecrow). No subscription anywhere. This mirrors how most of this hobbyist-hardware space monetizes: give away the network, sell (or drop-ship) the radios.

Docs/dev docs: MeshCore does not run a hosted docs site the way Meshtastic does. “Developer Docs” on the nav points straight to the GitHub repo (meshcore-dev/MeshCore), where a docs/ folder holds companion_protocol.md, packet_format.md, kiss_modem_protocol.md, cli_commands.md, etc. — plain Markdown, no rendered docs site, no search. A GitHub wiki existed but is noted (in their own FAQ) as being phased out in favor of the in-repo docs folder. Net effect: MeshCore’s marketing site (meshcore.co.uk) and its technical documentation live in two completely different places with two different levels of polish — the site is glossy, the protocol docs are bare Markdown you have to know to go looking for.

Web flasher / configurator: meshcore.co.uk/flasher.html is credited to a third-party contributor (“MeshCore Flasher by Rastislav Vysoky”) rather than being an official first-party tool, and links out to a separate /configurator/ for the “guided setup experience.” This two-tool split (flasher vs. configurator, one community-authored) is more fragmented than Meshtastic’s single official flasher+config flow, and it means MeshCore doesn’t fully control or brand its own most-important onboarding surface.

Strengths to note:

• “Three Steps. That’s It” is a genuinely strong, confident onboarding promise — simpler and punchier than Meshtastic’s multi-page hardware/ driver/firmware split.
• Two apps side-by-side (official vs. community) presented as a feature, not a fragmentation problem — reframes ecosystem diversity as choice.
• Standalone-device category (MeshOS, no-phone-required) is a real differentiated product tier the site foregrounds clearly with its own device gallery row.
• Social-proof numbers (users/countries/devices) up high, same instinct as Meshtastic, and it works.

Weaknesses chIRpChat’s site can beat:

• Developer/protocol docs are an afterthought — bare GitHub Markdown, no rendered site, no search, a wiki in the middle of being deprecated. chIRpChat’s docs/ are already normative, versioned, and detailed (PROTOCOL.md, ROUTING.md, IDENTITY.md); publishing them as a real docs site with search and navigation is an immediate, low-effort win over MeshCore’s approach.
• The flasher isn’t officially owned — attributing the primary onboarding tool to a third party (how ever appreciated) signals the core team hasn’t invested in first-run experience the way Meshtastic has. chIRpChat should ship (or clearly co-brand) its own flasher.
• No engineering-rigor story anywhere on the site. Nothing about test coverage, wire-format stability guarantees, threat modeling, or scaling honesty. chIRpChat’s ENGINEERING_DEEP_DIVE.md and docs/research/routing-redesign/ROUTING_THREAT_MODEL.md are unusually rigorous artifacts for this hobbyist space — nobody else is showing this kind of work publicly, and doing so is a differentiator in itself.
• “End-to-End Encrypted” is asserted as an unqualified virtue with no discussion of the trade-offs (key distribution, no plaintext auditability/moderation, no public verifiable-origin model). chIRpChat’s honest “we chose plaintext + signed identity, here’s exactly why and what it costs” (COMPARISON.md, IDENTITY.md) is a more sophisticated, defensible position for the audience that reads past the hero section.
• No IRC-client story, obviously (not their model) — but more generally, no site in this space addresses “I don’t want to install another app” as a first-class need. That’s chIRpChat’s single cleanest wedge.
• Client apps are the whole game, and they’re proprietary-flavored (a hosted web app on a different domain, app.meshcore.nz, plus a community app) — brittle information architecture (users must remember two domains) that chIRpChat’s “any IRC client, one server address” approach avoids entirely.

1.3 Cross-cutting observations for chIRpChat’s site

• Both competitors put a numbers band directly under the hero (devices/ contributors/regions/languages for Meshtastic; users/countries/devices for MeshCore). chIRpChat is pre-1.0 and should not fake this — Section 4 below proposes an honest substitute (a “state of the project” band, mirror of the README table, not vanity metrics).
• Both bury the protocol-level differentiation below feature-adjective soup (“Long Range,” “Encrypted,” “Fully Decentralised”). chIRpChat’s real differentiators (router/cellular architecture, asymmetric multi-SF routing, IRC compatibility) are structural claims that need one dedicated comparison page with a real table, not just hero adjectives — see docs/COMPARISON.md, which already exists in exactly this shape and should be transcribed near-verbatim into the site.
• Neither site really explains routing in the landing flow (it’s “mesh,” full stop, on both). chIRpChat’s asymmetric forward/return-lane routing (ENGINEERING_DEEP_DIVE.md §4.3) is the single most technically novel claim available and deserves its own diagram somewhere reachable from the hardware/why-chirpchat pages, not just buried in docs.
• Both flashers are browser-based, Web-Serial-driven, Chrome/Edge-only. This is now the default expectation for this hardware category — the chIRpChat flasher should match that baseline (Section 3) rather than regress to “download our desktop app.”

---

2. Proposed sitemap

/                              Landing
/why-chirpchat/                vs. Meshtastic & MeshCore (the honest comparison)
/hardware/                     Supported boards, buy links, "what to buy first"
/getting-started/              Buy → flash → connect → first message (single-path funnel)
/flash/                        Web flasher (ESP Web Tools / Web Serial)
/docs/                         Mirrors repo docs/ (see 2.1)
/blog/                         Engineering + project-update posts
/community/                    Discord/Matrix, GitHub, contributing, code of conduct
/download/                     Firmware release archive, daemon binaries, source links
/status/  (optional, post-launch) live network/build status, not launch-blocking

2.1 /docs/ — mirrors docs/ in the lrc repo

Docs nav groups (left sidebar), each backed by an existing repo doc so there is no content invention:

• Start here
  • Introduction / What is chIRpChat (new page, synthesized from README + ENGINEERING_DEEP_DIVE §1)
  • Quickstart (new page; distilled from README “Build” + USERGUIDE.md)
• Concepts
  • Architecture → ARCHITECTURE.md
  • Comparison vs. Meshtastic/MeshCore → COMPARISON.md
  • Engineering Deep Dive → ENGINEERING_DEEP_DIVE.md (published close to verbatim — it’s written for exactly this audience)
• Protocol reference
  • Wire format (LPP v1) → PROTOCOL.md
  • Identity, keys, tags, checkpoints → IDENTITY.md
  • Routing, federation, channel ownership → ROUTING.md
  • Radio: lanes, presets, probing, DCC → RADIO.md
  • Storage: flash/PSRAM tiers → STORAGE.md
  • Power: sleep states → POWER.md
• Running it
  • User guide (everything from inside your IRC client) → USERGUIDE.md
  • Hardware & boards → HARDWARE.md
  • Telemetry & field debugging → TELEMETRY.md
  • Testing → TESTING.md
  • USB networking (CDC-ECM/NCM) → USB_NCM_PLAN.md
• Security
  • Security audit → SECURITY_AUDIT.md
  • Security policy/reporting → SECURITY.md (repo root)
• Project
  • Roadmap → ROADMAP.md
  • Release 1.0 readiness → RELEASE_1.0_READINESS.md
  • Research (labeled clearly as non-normative/exploratory) → research/ALT_ROADMAP_BEYOND.md, research/CROSSFED_DM.md, research/routing-redesign/*
  • Contributing → CONTRIBUTING.md
  • Agent guidance → AGENTS.md (interesting/differentiating to publish — “most contributors here are AI agents” is a genuinely notable, honest detail worth its own docs page or blog post, not hidden)

Research-tier docs (routing-redesign, ALT_ROADMAP_BEYOND) get a visible “Research / Not Yet Shipped” badge in the docs sidebar and a banner on the page itself, generated automatically from the same front-matter flag used to gate the site build (Section 3) — never silently presented as normative.

---

3. Tech stack recommendation

Recommendation: Astro + Starlight, deployed to Cloudflare Pages.

Evaluated against Docusaurus and Hugo:

	Astro + Starlight	Docusaurus	Hugo
Landing page flexibility	Full Astro component freedom — hero, custom comparison tables, interactive flasher island, blog, all one framework	Landing page is a bolted-on React page outside the docs plugin; workable but visibly a “docs site with a homepage stapled on” (which is exactly the feel of meshtastic.org today)	Landing page is just another template; flexible but no component islands, all custom JS is hand-wired
Docs-from-Markdown	Starlight is purpose-built for exactly this: sidebar config from frontmatter, versioning-lite, search (Pagefind) out of the box, dark mode, i18n if ever needed	Best-in-class docs plugin (this is what Meshtastic itself runs on) — mature, versioned docs, MDX	Good but docs navigation/sidebar is hand-rolled in templates/config; no first-party “docs mode”
Build output / CF Pages fit	Static output by default; Cloudflare adapter is first-party and simple; ships zero JS unless a component opts in (client:load etc.) — fastest possible Lighthouse scores, which matters for a site whose own selling point is engineering discipline	Static export works fine on CF Pages; React runtime shipped for interactivity even where none is needed	Fastest possible builds (Go binary), purely static, zero JS by default — but then WebSerial flasher needs a hand-written vanilla-JS page outside the templating system
Interactive flasher integration	Natural: the flasher is one Astro “island” (a small Preact/vanilla component with client:only), rest of page stays static. Astro’s partial-hydration model is exactly suited to “one interactive widget on an otherwise static docs/marketing site.”	Works, but every MDX page that wants to embed a live component pulls in more of the React runtime; less naturally scoped	Would require a separate hand-built JS bundle pipeline (esbuild/vite alongside Hugo) since Hugo itself has no component/hydration model — an extra moving part
Content-sync from repo docs/	Straightforward: a sync script (Section 3.1) copies/transforms lrc/docs/*.md into src/content/docs/, adding Starlight frontmatter; Starlight’s content-collections schema validates as part of astro build, so a stale/malformed sync fails CI, not production	Same idea works (Docusaurus also reads plain Markdown/MDX with frontmatter) — comparable effort	Hugo’s content model is also just files-with-frontmatter, so also comparable — this axis is roughly a wash across all three
Team fit	Modern, small footprint, TypeScript-friendly, minimal config; a single maintainer (or small AI-agent-heavy contributor base, per this repo’s own AGENTS.md) can hold the whole site’s mental model in their head	Larger surface area (webpack/React internals occasionally leak through when something breaks); most mature ecosystem if the team ever wants swizzling/deep plugin customization	Simplest mental model for pure docs, but landing-page-plus-interactive-flasher pushes past what Hugo is good at
Ecosystem precedent	Increasingly the default choice for new technical-product docs sites (Astro’s own docs, many CLI tool docs)	What Meshtastic itself runs — chIRpChat matching it exactly would look derivative; differentiating on tech feel (fast, custom landing) reinforces the “we sweat the engineering” positioning	Used by Hugo’s own site and many static blogs; less suited to the marketing+docs+interactive-tool combination this project needs

Why Astro+Starlight wins for this specific project: the site needs three things at once — a fully custom, opinionated landing/comparison page (not just docs), a large normative docs corpus synced from lrc/docs/, and one genuinely interactive widget (the web flasher). Starlight solves the docs half completely (sidebar/search/versioning-lite come free); Astro’s island-architecture solves the flasher half without dragging a JS framework runtime into every page. Docusaurus can do all of this too but ships more JS by default and is what Meshtastic already runs — differentiating with a leaner, faster-loading stack is itself a small, honest marketing point for a project whose core pitch is “we sweat details others don’t.” Hugo is excluded mainly because the interactive flasher would live outside Hugo’s templating/component model entirely, adding a second build pipeline for one critical page.

3.1 Syncing repo docs/ into the site

The lrc repo’s docs/*.md are normative and move with behavior (per AGENTS.md); the website repo must not fork them into a second source of truth. Plan:

• A small Node/TS script (scripts/sync-docs.ts) in the website repo clones or fetches lrc (as a git submodule pinned to a tag, not a live main checkout — avoids the site breaking on every unrelated repo commit) and copies the mapped files from Section 2.1 into src/content/docs/<section>/, injecting Starlight frontmatter (title, sidebar.order, badge for research-tier docs) either from a small YAML manifest in the website repo or from a <!-- site: key: value --> comment convention added to the source docs later if the team wants it self-describing.
• Internal doc-to-doc links ([ROUTING.md](https://github.com/h3lix1/lrc/blob/main/docs/research/ROUTING.md)) get rewritten to site paths (/docs/protocol/routing/) by the sync script via a simple filename → route lookup table — this is the one piece of real transformation logic needed, everything else is a copy.
• The sync runs (a) manually via npm run sync-docs when the lrc submodule pin is bumped, and (b) in CI on a schedule (e.g. weekly) opening an automated PR if the submodule has moved upstream, so docs drift is visible and reviewed rather than either frozen forever or silently auto-deployed.
• ENGINEERING_DEEP_DIVE.md and COMPARISON.md are prime candidates for light editorial pass (not content changes — tone/link adjustments only) since they’re already written in a voice suited to public consumption; the rest sync verbatim.
• Research-tier docs sync into a clearly-badged /docs/research/ section with a banner component (“Exploratory — not yet shipped behavior”) driven by their source path, not manual tagging, so nothing research-only can silently read as normative on the site.

3.2 Web flasher integration

• Use ESP Web Tools (the esp-web-tools web component from Espressif, distinct from but architecturally identical to what Meshtastic’s own flasher builds on top of the Web Serial API) as the base, or bind directly to esptool-js for tighter control over the multi-target (XIAO ESP32S3, Heltec WiFi LoRa 32 V3) selection UI chIRpChat needs. Recommendation: esptool-js directly, wrapped in a small Astro/Preact island — esp-web-tools’s manifest format assumes a single simple flash target and chIRpChat already has two boards with different partition layouts (per HARDWARE.md/firmware/variants/), so direct esptool-js control over the manifest is worth the slightly higher integration cost.
• Firmware binaries for the flasher are published as GitHub Release assets from the lrc repo’s firmware CI (new: a release job that runs pio run -e xiao_wio_sx1262 / the Heltec env and uploads the .bin + partition table); the website’s flasher page fetches the manifest listing available releases/boards at build time or via a small Cloudflare Worker/Pages Function if release listing needs to be live rather than rebuilt-on-deploy.
• Chrome/Edge-only reality (Web Serial isn’t in Safari/Firefox) gets an explicit, friendly banner — matching Meshtastic’s honest framing rather than hiding the limitation.
• The flasher page also embeds a plain-language fallback: “no Chrome/Edge? Use pio run -e xiao_wio_sx1262 -t upload from a terminal” with a link to /docs/running-it/hardware/, so the browser tool is additive, not a hard gate on getting a device flashed.

3.3 Cloudflare Pages fit

• Astro’s official @astrojs/cloudflare adapter targets Pages directly; static output (docs/landing/blog) needs no adapter at all (pure static upload), and only the flasher island needs client JS — no server-side Cloudflare Worker functions are required for MVP. Keeps the whole site on Cloudflare Pages’ free/static tier.
• If live release-listing (Section 3.2) is added later, that one endpoint becomes a Cloudflare Pages Function (functions/api/releases.ts) calling the GitHub Releases API server-side, avoiding a client-side GitHub token.

---

4. Landing page copy draft

Hero headline options (pick one; all are grounded in real, load-bearing claims)

1. “Any IRC client. A LoRa mesh. Nothing in between to install.” (near-verbatim from README — the strongest, most concrete claim; leads with the zero-app wedge that neither competitor can say.)
2. “The LoRa mesh that speaks IRC.” (shorter, punchier; good above-the-fold headline with (1) as subhead.)
3. “Off-grid chat, without another app to trust.” (leans into the “you already have a client” framing, contrasts against both competitors’ app-required model without naming them in the hero.)
4. “A LoRa network that behaves like infrastructure, not a walkie-talkie.” (leads with the architecture differentiator instead of the client story; better for a technical/engineering-first audience landing from HN/the blog rather than a general “I want off-grid chat” searcher.)

Recommended pairing: headline (2) + subhead (1), because it’s scannable in under two seconds and the subhead immediately cashes the promise with a concrete, testable claim (irssi/WeeChat, no app) rather than an adjective.

Value-prop blocks (4, ordered for a first-time visitor)

1. No app to install

Point any IRC client — irssi, WeeChat, HexChat, or anything from the last thirty years — at your chIRpChat node and you’re on the mesh. /server 10.97.83.1 6667, /join #pizza, done. The client problem was already solved; chIRpChat doesn’t ask you to solve it again.

2. Built like a cell network, not a walkie-talkie

Meshtastic and MeshCore flood every message to every node in earshot. chIRpChat’s routers sequence traffic and clients register — like phones to cell towers — so a busy channel costs one transmission per access network, not one per listener. Routers federate over the internet when it’s there and keep working over RF when it isn’t.

3. Signed, public, and honest about it

chIRpChat doesn’t encrypt chat — it signs it. Every message carries a verifiable Ed25519-rooted identity, escalating from a cheap per-message tag to periodic full signatures, so origin is provable without a shared secret to manage or lose. If you need confidentiality, Meshtastic or MeshCore are the right tool — different charter, different guarantees, and we say so plainly.

4. Loss is expected, and healed automatically

Every channel is sequence-numbered per router. A missed message isn’t gone — it’s a gap, and gaps get backfilled the same way whether you missed five minutes or five days, whether you’re rejoining after a reboot or catching up on scrollback for the first time. The network is a write-ahead log, not a best-effort shout.

5. Multi-speed radio that adapts to physics

A router on a hill can reach you fast; you often can’t reach it back at the same speed. chIRpChat measures the asymmetry and picks the return path that actually clears the link — the first LoRa mesh stack to treat forward and return legs as the physically different problems they are.

(Ship all 5 if the landing page has room; if trimming to match competitor landing-page density, cut #5 to a “learn more” link into /why-chirpchat/ and keep the top 4 above the fold.)

Call-to-action flow

1. Primary CTA (hero): “See how it works” → /getting-started/ (not straight to the flasher — first-time visitors need the 30-second mental model before a binary-flashing tool).
2. Secondary CTA (hero): “Why not Meshtastic / MeshCore?” → /why-chirpchat/ (captures the technically-literate visitor who arrived already comparing options — likely the majority of early traffic, given the launch audience is Meshtastic/MeshCore communities).
3. Getting-started page CTA chain: Buy hardware (→ /hardware/) → Flash it (→ /flash/, the web flasher) → Connect your IRC client (inline 3-line snippet, identical to the README’s) → Join #chirpchat (a real, always-on welcome channel — first message success is confirmed the moment /join returns names, no separate “it worked!” page needed).
4. Tertiary, present throughout via header: “Docs” and “GitHub” — the technical-credibility escape hatches for visitors who bounce off marketing copy and want ground truth immediately.
5. Footer CTA: Discord/Matrix community link + “Read the Engineering Deep Dive” (the single best credibility artifact in the repo, and a fitting final CTA for a visitor who scrolled the whole page).

---

5. Content inventory (launch-ready page list)

Marketing / top-level

Page	Brief
/ Landing	Hero, 4-5 value props, state-of-project band, CTA chain (Section 4).
/why-chirpchat/	The honest comparison — transcribes COMPARISON.md’s table plus the “what chIRpChat gives up” section verbatim; this page is the site’s credibility anchor.
/hardware/	Supported boards (XIAO ESP32S3 + Wio-SX1262, Heltec WiFi LoRa 32 V3, RAK4631 compile-only/untested — labeled honestly), buy links, “what to buy first” recommendation (XIAO combo, per README’s primary target).
/getting-started/	Single linear funnel: buy → flash → connect → first /join. No branching until the user has succeeded once.
/flash/	The web flasher tool (Section 3.2) plus CLI fallback instructions.
/download/	Firmware release archive (GitHub Releases mirror), lrcd daemon binaries/build instructions, source links.
/community/	Discord/Matrix invite, GitHub link, CONTRIBUTING.md summary + link, Code of Conduct, note on AI-agent contributors (per AGENTS.md — an honest, distinctive detail).
/blog/	Index page; see Section 6 for seed posts.
/security/	Summarized SECURITY.md (reporting process) + link to SECURITY_AUDIT.md in docs — security-conscious visitors look for this page specifically and bounce if it’s missing.

Docs (see Section 2.1 for the full mapped tree)

Page	Brief
/docs/ index	What’s normative vs. research, how to navigate, link to /why-chirpchat/ for the elevator pitch.
/docs/intro/	New synthesis page: what chIRpChat is in one paragraph (adapted from ENGINEERING_DEEP_DIVE.md §1) + link map to the rest of docs.
/docs/quickstart/	New page: the README build/flash commands, formatted for a docs reader rather than a repo reader.
~15 mirrored pages	Direct syncs per the Section 2.1 table — no new writing needed, only frontmatter + link-rewrite.

Image / asset list

• Hero device photo(s): XIAO ESP32S3 + Wio-SX1262 combo, photographed plugged into USB with an antenna attached (matches the RF-safety framing in HARDWARE.md/AGENTS.md — never show it without an antenna, to avoid modeling unsafe use). Needs to be shot; nothing in-repo today.
• Heltec WiFi LoRa 32 V3 product photo for the hardware page — likely usable from the manufacturer’s press kit with attribution, or shot in-house.
• Architecture diagram: adapt the ASCII diagram in ARCHITECTURE.md (client ↔ lrc-node ↔ lrc-router, with USB-ECM/WiFi and LoRa-lane/TCP legs) into a clean SVG for the landing/why-chirpchat pages.
• Cellular-vs-flood comparison diagram: new — a simple two-panel graphic contrasting “everyone floods to everyone” (Meshtastic/MeshCore) against “clients register to routers, routers federate” (chIRpChat); this is the single most important explanatory image on the site since it’s the crux of /why-chirpchat/.
• Asymmetric-lanes diagram: new — a simple two-panel graphic to visualize the SF5-forward/SF12-return scenario described in ENGINEERING_DEEP_DIVE.md §4.3 — a hill-router, a hidden client, two arrows of different “speed” going opposite directions. This is the headline technical differentiator and currently has no visual anywhere.
• CHANSYNC gap-healing diagram: small sequence diagram (timeline with a gap, a grace period, a REQ/RESP pair, backfilled messages) — supports the “network as WAL” value prop.
• Screenshot: irssi/WeeChat connected to a chIRpChat node — the single most important screenshot on the whole site, since it’s proof of the “no app” claim; needs to be captured against a real running lrcd or firmware node.
• Screenshot: TUI over telnet (lrcd’s ircii-style TUI on :2323) — supports the “one codepath, two faces” architecture claim.
• Screenshot: lrcctl watch — a terminal capture of live lrcctl watch output, useful for the /docs/ operator-facing pages and a blog post.
• QR-code key export photo/screenshot: the hand-rolled Reed-Solomon QR-v4-L phonetic key export over serial (ENGINEERING_DEEP_DIVE.md §12) is a genuinely fun, differentiated detail worth a screenshot on either /docs/identity/ or its own blog post.
• Favicon/logo/wordmark: does not exist yet anywhere in the repo — needs original design work before launch; not gatable on this plan but flagged as a hard launch blocker.

---

6. Blog post seed list (6-10 launch-window posts)

1. “Why we didn’t use protobuf” — the LPP wire-format design story: 255-byte ceiling, zero-allocation radio path, strict decode, golden-byte pinning via packet_golden_bytes and the lrc-wire-change skill. Drawn from ENGINEERING_DEEP_DIVE.md §2.

2. “Cellular, not mesh: why chIRpChat’s routers act like cell towers” — the core architectural thesis, contrasting flood routing against registration + directed paths + federation. Drawn from ENGINEERING_DEEP_DIVE.md §4.1 and COMPARISON.md.

3. “The asymmetric routing problem nobody else is solving” — the SF5-forward/SF12-return story, return_lane.h’s delivery-probability- per-airtime objective, why “fastest link” and “best link” aren’t the same question on LoRa. Drawn from ENGINEERING_DEEP_DIVE.md §4.3 — the flagship technical post for launch.

4. “Redesigning routing from scratch: a two-track adversarial review” — the story of the routing-redesign process itself: an async-routing design track and a threat-model track reconciled against a 14-point requirements contract (R1-R14), with a documented NEEDS-ROUNDTRIP → CONSOLIDATED pass-2 verdict. A rare, honest look at how a protocol change actually gets vetted before it touches the wire. Drawn from docs/research/routing-redesign/CONSOLIDATED_ROUTING_PLAN.md.

5. “Four tiers of trust, from tripwire to signature” — the ingress- attestation → Tag8 → checkpoint → full-signature escalation, and the canonical-image trick that lets relays mutate frames without invalidating signatures. Drawn from ENGINEERING_DEEP_DIVE.md §3.1-3.2.

6. “What happens when you lose your key” — an unflinching post about IK-compromise being permanent and unrecoverable by design, why there’s no escrow, and what rotation does and doesn’t protect against. Honesty as a feature; drawn from ENGINEERING_DEEP_DIVE.md §3.5.

7. “We dodge Meshtastic and MeshCore’s frequencies on purpose” — the SipHash(region, lane_index)-seeded frequency planner that avoids every Meshtastic modem preset and three coordinated MeshCore metro channels with guard bands, so a chIRpChat node is a good spectrum neighbor out of the box. Drawn from ENGINEERING_DEEP_DIVE.md §6.2 — good goodwill-building post for both competing communities.

8. “Why chIRpChat won’t scale to a million users on one router (and why that’s fine)” — the honest scaling ceiling discussion: per-router limits, the federation path to hundreds of thousands of users, and the real remaining walls (airtime, directory growth, single-thread lrcd, no global DHT). Drawn from ENGINEERING_DEEP_DIVE.md §9.

9. “The USB cable is the onboarding” — the CDC-ECM story: plug in, get DHCP, point any IRC client at 10.97.83.1:6667, no drivers, no app. Drawn from README + docs/USB_NCM_PLAN.md; pairs naturally with a launch demo GIF/video.

10. “Most of our contributors are AI agents, and the docs are written for them” — a meta post about AGENTS.md, the wire-change and test-adding skills, and what it means to write normative documentation as an executable contract rather than prose. Genuinely novel framing for a hobbyist-radio blog audience; drawn from AGENTS.md and CONTRIBUTING.md.

---

7. Repo / deploy plan

Repo name: chirpchat-site (organization-level, separate from lrc; keeps the marketing/docs site’s commit history, issue tracker, and contributor surface distinct from the core protocol repo per the task’s requirement to live in a new repo). Alternative if the org prefers a docs-first name: chirpchat.dev or chirpchat-www.

Domain: chirpchat.dev primary (developer-audience-appropriate TLD, available-pending-check), with www.chirpchat.dev redirecting to the apex. chirpchat.chat as a stretch/secondary if available — strong vanity fit given the product, worth a quick registrar check before launch but not a blocker.

Cloudflare Pages config:

• Framework preset: Astro.
• Build command: npm run sync-docs && npm run build (the doc-sync step runs before every build so main deploys never drift from the pinned lrc submodule without a review step catching it first).
• Build output directory: dist/.
• Node version: pin via .nvmrc/engines field (LTS at time of scaffolding).
• Environment variables: none required for MVP (fully static except the flasher island, which is client-side only); if live release-listing (Section 3.2) is added, a GITHUB_TOKEN secret scoped read-only to Releases goes in the Pages Function environment, not the build environment.

Preview deploys: Cloudflare Pages’ default behavior — every PR gets a unique <hash>.chirpchat-site.pages.dev preview URL automatically; no extra config needed beyond connecting the GitHub repo. Recommend branch protection on main requiring the preview build to succeed before merge, mirroring the rigor of the lrc repo’s own verify loop.

Custom domain checklist:

1. Register chirpchat.dev (or chosen domain).
2. Add the domain as a Cloudflare zone (or transfer DNS to Cloudflare if registered elsewhere) — Pages custom domains work best when Cloudflare also holds the DNS.
3. In Pages project settings → Custom domains → add chirpchat.dev and www.chirpchat.dev; Cloudflare auto-provisions the CNAME/edge certificate.
4. Set www → apex redirect (or vice versa, pick one canonical host) via a Cloudflare redirect rule, not a client-side JS redirect.
5. Verify flasher/download subresources aren’t blocked by any CSP added later (Web Serial API requires a secure context — https:// — which Pages provides by default, but double-check any custom _headers file doesn’t add a restrictive Permissions-Policy that disables serial).
6. Add the domain to the lrc repo’s README/docs pointers once live (a small follow-up PR in the lrc repo itself, out of scope for this plan but worth flagging so it isn’t forgotten).
7. Set up basic uptime/deploy-failure alerting (Cloudflare’s own Pages deployment notifications are sufficient for launch; no extra service needed).

---

This plan proposes; it does not build. No website repo, build tooling, or deploy has been created as part of writing this document.