serverless-ircd 0.8.0 → 0.10.0

package/apps/local-cli/tests/tcp.test.ts

@@ -215,6 +215,24 @@ describe('local-cli TCP transport — IRC flows', () => {
     await client.close();
   });
 
+  it('skips an empty line delivered over TCP without dispatching it', async () => {
+    // The LineScanner yields an empty string for a bare CRLF; the data
+    // handler's `if (line.length === 0) continue` must skip it without
+    // feeding an empty IRC line to the actor (server.ts:539).
+    const client = new TcpTestClient('127.0.0.1', server.tcpPort as number);
+    await client.opened();
+    await client.send('NICK blanker');
+    await client.send('USER blanker 0 * :Blanker');
+    await client.waitFor((l) => l.startsWith(':irc.local.example.com 001 '));
+
+    // A bare CRLF (blank line) followed by a valid PING: the blank line is
+    // ignored and the PING still resolves to a PONG.
+    await client.writeRaw('\r\n');
+    await client.send('PING :after-blank');
+    await client.waitFor((l) => l === 'PONG :after-blank');
+    await client.close();
+  });
+
   it('processes multiple IRC lines delivered in a single TCP write', async () => {
     const client = new TcpTestClient('127.0.0.1', server.tcpPort as number);
     await client.opened();
@@ -367,6 +385,31 @@ describe('local-cli TCP transport — shutdown', () => {
     expect(client.socket.destroyed).toBe(true);
   });
 
+  it('close() destroys a still-live registered TCP connection via the close sweep', async () => {
+    // Registering the client (awaiting 001) guarantees the server-side
+    // connection handler has run and the socket is in `tcpConnections`, so
+    // `close()` deterministically enters the close sweep (server.ts:765) and
+    // destroys the live socket. (Connecting without registering races the
+    // handler under coverage instrumentation.)
+    const srv = await startLocalServer({
+      port: 0,
+      tcpPort: 0,
+      hostname: '127.0.0.1',
+      serverName: 'irc.local.example.com',
+      networkName: 'LocalNet',
+    });
+    const client = new TcpTestClient('127.0.0.1', srv.tcpPort as number);
+    await client.opened();
+    await client.send('NICK sweepUser');
+    await client.send('USER sweepUser 0 * :Sweep');
+    await client.waitFor((l) => l.startsWith(':irc.local.example.com 001 '));
+
+    const closed = new Promise<void>((resolve) => client.socket.once('close', () => resolve()));
+    await srv.close();
+    await closed;
+    expect(client.socket.destroyed).toBe(true);
+  });
+
   it('close() is a no-op for TCP when tcpPort was never enabled', async () => {
     const srv = await startLocalServer({
       port: 0,
@@ -408,3 +451,49 @@ describe('local-cli TCP transport — shutdown', () => {
     await srv.close();
   });
 });
+
+describe('local-cli TCP transport — admission gate', () => {
+  it('emits ERROR :Closing link and destroys the socket when admitConnection denies', async () => {
+    // Tight per-IP cap with a permissive rate limit so only the per-IP
+    // simultaneous-connection gate refuses the second connection.
+    const srv = await startLocalServer({
+      port: 0,
+      tcpPort: 0,
+      hostname: '127.0.0.1',
+      serverName: 'admit.example.com',
+      networkName: 'AdmitNet',
+      maxConnectionsPerIp: 1,
+      maxConnectionsPerUser: 1_000,
+      perIpConnectionRate: { max: 1_000, windowMs: 60_000 },
+    });
+
+    try {
+      // First connection fills the per-IP cap (maxConnectionsPerIp: 1).
+      const first = new TcpTestClient('127.0.0.1', srv.tcpPort as number);
+      await first.opened();
+
+      // Second connection from the same IP is denied at the TCP admission
+      // gate BEFORE an actor is attached. The server writes the RFC-style
+      // ERROR notice then destroys the socket (server.ts 511-517).
+      const rejected = new TcpTestClient('127.0.0.1', srv.tcpPort as number);
+      const errorLine = await rejected.waitFor((l) => l.startsWith('ERROR :Closing link'), 2_000);
+      expect(errorLine).toContain('connection limit reached');
+      expect(errorLine).toContain('max_connections_per_ip');
+
+      // The server destroys the socket after the ERROR notice.
+      await new Promise<void>((resolve) => {
+        if (rejected.socket.destroyed) resolve();
+        else rejected.socket.once('close', () => resolve());
+      });
+      expect(rejected.socket.destroyed).toBe(true);
+
+      // The denied socket is removed from the server's tracked set so the
+      // runtime admission counters don't leak it.
+      expect(srv.testTcpSockets?.has(rejected.socket)).toBe(false);
+
+      await first.close();
+    } finally {
+      await srv.close();
+    }
+  });
+});

package/apps/local-cli/tests/ws-subprotocol.test.ts

@@ -171,6 +171,20 @@ describe('local-cli IRCv3 WebSocket subprotocol', () => {
     await client.close();
   });
 
+  it('falls back to legacy framing when only unsupported protocols are offered', async () => {
+    // `selectSubprotocol` returns undefined for an all-unsupported offer, so
+    // `handleProtocols` returns false and the ws library completes the
+    // handshake with no negotiated subprotocol. Exercises the
+    // `?? false` fallback in handleProtocols. The offering client then
+    // aborts ("Server sent no subprotocol"), which is expected — the
+    // server-side branch is what this covers.
+    const client = new SpecClient(`ws://127.0.0.1:${server.port}/`, ['chat']);
+    client.ws.on('error', () => {
+      // Expected: server returned no subprotocol for an all-unsupported offer.
+    });
+    await expect(client.opened()).rejects.toThrow(/no subprotocol/iu);
+  });
+
   it('completes registration with one IRC message per WebSocket message (text mode)', async () => {
     const client = new SpecClient(`ws://127.0.0.1:${server.port}/`, 'text.ircv3.net');
     await client.opened();
@@ -260,3 +274,81 @@ describe('local-cli IRCv3 WebSocket subprotocol', () => {
     });
   }
 });
+
+describe('local-cli WebSocket — transport seams', () => {
+  let server: LocalServer;
+
+  beforeAll(async () => {
+    server = await startLocalServer({
+      port: 0,
+      hostname: '127.0.0.1',
+      serverName: 'seam.example.com',
+      networkName: 'SeamNet',
+    });
+  });
+
+  afterAll(async () => {
+    await server.close();
+  });
+
+  it('logs a spec-mode actor failure without crashing the server', async () => {
+    // Register normally first so the connection has a nick, then swap the
+    // runtime send to throw — the next inbound message's dispatch rejects
+    // inside receiveTextFrame and the spec-mode `.catch` (server.ts:453)
+    // routes it to logError instead of crashing the server.
+    const client = new SpecClient(`ws://127.0.0.1:${server.port}/`, 'text.ircv3.net');
+    await client.opened();
+    await client.send('NICK specErr');
+    await client.send('USER specErr 0 * :Spec Err');
+    await client.waitFor((l) => l.startsWith(':seam.example.com 001 '));
+
+    const original = server.runtime.send.bind(server.runtime);
+    server.runtime.send = async () => {
+      throw new Error('synthetic spec send failure');
+    };
+    try {
+      // PING dispatches a Send effect → synthetic throw → actor catch.
+      await client.send('PING :will-throw');
+      await new Promise((r) => setTimeout(r, 60));
+    } finally {
+      server.runtime.send = original;
+    }
+
+    // The server must still serve fresh spec-mode connections.
+    const next = new SpecClient(`ws://127.0.0.1:${server.port}/`, 'text.ircv3.net');
+    await next.opened();
+    await next.send('NICK specRecover');
+    await next.send('USER specRecover 0 * :Spec Recover');
+    await next.waitFor((l) => l.startsWith(':seam.example.com 001 '), 2_000);
+    await next.close();
+    await client.close();
+  });
+
+  it('drops an outbound send to a WebSocket that is no longer OPEN', async () => {
+    // Register, then transition the server-side ws to CLOSING. The runtime
+    // still tracks the connection until the 'close' event fires on a later
+    // tick, so a synchronous dispatch hits the `ws.readyState !== OPEN`
+    // guard and returns before calling ws.send (server.ts:423).
+    const client = new SpecClient(`ws://127.0.0.1:${server.port}/`, 'text.ircv3.net');
+    await client.opened();
+    await client.send('NICK dropSend');
+    await client.send('USER dropSend 0 * :Drop');
+    await client.waitFor((l) => l.startsWith(':seam.example.com 001 '));
+
+    const connId = await server.runtime.lookupNick('dropSend');
+    expect(connId).not.toBeNull();
+    const serverWs = [...server.testSockets].find((ws) => ws.readyState === WebSocket.OPEN);
+    expect(serverWs).toBeDefined();
+    serverWs?.close();
+    // Synchronous dispatch before the 'close' cleanup runs: the send handler
+    // must observe readyState !== OPEN and no-op without throwing.
+    await expect(
+      server.runtime.send(connId as string, [{ text: ':seam NOTICE dropSend :dropped' }]),
+    ).resolves.toBeUndefined();
+
+    await new Promise<void>((resolve) => {
+      client.ws.once('close', () => resolve());
+      client.ws.close();
+    });
+  });
+});

package/apps/web/landing/index.html

@@ -4,12 +4,14 @@
 
   Served at `/` by the Worker `[assets]` binding (apps/cf-worker/wrangler.toml).
   The build (`scripts/build.mjs`) copies this file verbatim to `dist/index.html`.
-  The Kiwi IRC SPA lives at `/webclient/`; this page links through to it plus
-  the project docs and source repo. Pure static HTML + inline CSS, no JavaScript.
+  The Kiwi IRC SPA lives at `/webclient/`; the rendered docs at `/docs/`
+  (built from the `docs/` submodule); this page links through to both plus
+  the source repo. Pure static HTML + inline CSS, no JavaScript.
 -->
 <html lang="en">
   <head>
     <meta charset="utf-8" />
+    <link rel="icon" href="/favicon.ico" sizes="any" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <title>ServerlessIRCd — Serverless IRC Daemon</title>
     <meta
@@ -135,6 +137,113 @@
         border-radius: 4px;
         font-size: 0.9em;
       }
+      pre {
+        font-family: var(--mono);
+        background-color: var(--surface);
+        border: 1px solid var(--border);
+        border-radius: 8px;
+        padding: 14px 16px;
+        margin: 12px 0;
+        overflow-x: auto;
+        line-height: 1.5;
+        font-size: 0.88rem;
+      }
+      pre code {
+        background: none;
+        border: none;
+        padding: 0;
+        font-size: inherit;
+      }
+      section.connect {
+        margin: 36px 0 8px;
+        padding: 24px 0;
+        border-top: 1px solid var(--border);
+      }
+      section.connect h2 {
+        margin: 0 0 12px;
+        font-size: 1.4rem;
+        letter-spacing: -0.01em;
+      }
+      section.connect h3 {
+        margin: 22px 0 6px;
+        font-size: 1.08rem;
+        color: var(--accent-hover);
+      }
+      section.connect p {
+        margin: 8px 0;
+        color: var(--text);
+      }
+      section.connect p.lead {
+        color: var(--muted);
+      }
+      section.connect .note {
+        color: var(--muted);
+        font-size: 0.92rem;
+      }
+      section.connect .cta {
+        margin: 14px 0;
+      }
+      /* Client picker — pure CSS, no JavaScript. Radio inputs hold the
+         selected tab; the labels are the visible buttons arranged in a
+         horizontal row; `:checked ~` reveals the matching panel and
+         highlights its label. See build-smoke "works without JavaScript". */
+      .client-tabs {
+        margin: 8px 0 4px;
+      }
+      .client-tabs > input[type="radio"] {
+        position: absolute;
+        opacity: 0;
+        pointer-events: none;
+      }
+      .client-tabs .tablist {
+        display: flex;
+        flex-wrap: wrap;
+        gap: 8px;
+        margin-bottom: 16px;
+      }
+      .client-tabs .tablist label {
+        padding: 10px 16px;
+        cursor: pointer;
+        border: 1px solid var(--border);
+        border-radius: 8px;
+        background-color: var(--surface);
+        color: var(--muted);
+        font-weight: 600;
+        font-size: 0.95rem;
+        -webkit-tap-highlight-color: transparent;
+        transition: border-color 0.15s, color 0.15s, background-color 0.15s;
+      }
+      .client-tabs .tablist label:hover {
+        border-color: var(--accent);
+        color: var(--text);
+      }
+      .client-tabs .panel {
+        display: none;
+      }
+      .client-tabs .panel h3 {
+        margin-top: 0;
+      }
+      #tab-web:checked ~ .tablist label[for="tab-web"],
+      #tab-weechat:checked ~ .tablist label[for="tab-weechat"],
+      #tab-hexchat:checked ~ .tablist label[for="tab-hexchat"],
+      #tab-irccloud:checked ~ .tablist label[for="tab-irccloud"] {
+        background-color: var(--bg);
+        color: var(--accent-hover);
+        border-color: var(--accent);
+      }
+      #tab-web:focus-visible ~ .tablist label[for="tab-web"],
+      #tab-weechat:focus-visible ~ .tablist label[for="tab-weechat"],
+      #tab-hexchat:focus-visible ~ .tablist label[for="tab-hexchat"],
+      #tab-irccloud:focus-visible ~ .tablist label[for="tab-irccloud"] {
+        outline: 2px solid var(--accent);
+        outline-offset: 2px;
+      }
+      #tab-web:checked ~ #panel-web,
+      #tab-weechat:checked ~ #panel-weechat,
+      #tab-hexchat:checked ~ #panel-hexchat,
+      #tab-irccloud:checked ~ #panel-irccloud {
+        display: block;
+      }
       .links {
         margin-top: 28px;
         padding: 20px 0;
@@ -170,7 +279,7 @@
     <header>
       <div class="container">
         <h1>Serverless<span class="irc">IRCd</span></h1>
-        <p>An IRC daemon with a serverless deployment model.</p>
+        <p>IRC daemon with a serverless deployment model.</p>
       </div>
     </header>
 
@@ -194,7 +303,122 @@
           <a class="primary" href="/webclient/">Launch Web Client</a>
         </div>
 
+        <section class="connect">
+          <h2>Connect</h2>
+          <p class="lead">
+            ServerlessIRCd speaks IRC over secure WebSocket
+            (<code>wss://</code>, port <code>443</code>) as its primary
+            transport, and optionally raw <code>irc+tls</code> on port
+            <code>6697</code>. Replace <code>irc.example.com</code> with your
+            deployed Worker hostname in the snippets below. This page is
+            static and identical across staging and prod.
+          </p>
+
+          <div class="client-tabs">
+            <input type="radio" name="client-tab" id="tab-web" checked />
+            <input type="radio" name="client-tab" id="tab-weechat" />
+            <input type="radio" name="client-tab" id="tab-hexchat" />
+            <input type="radio" name="client-tab" id="tab-irccloud" />
+
+            <div
+              class="tablist"
+              role="tablist"
+              aria-label="IRC client connect instructions"
+            >
+              <label for="tab-web" class="tab" role="tab">Web client</label>
+              <label for="tab-weechat" class="tab" role="tab">WeeChat</label>
+              <label for="tab-hexchat" class="tab" role="tab"
+                >HexChat / irssi</label
+              >
+              <label for="tab-irccloud" class="tab" role="tab"
+                >IRCCloud / TheLounge</label
+              >
+            </div>
+
+            <div
+              class="panel"
+              id="panel-web"
+              role="tabpanel"
+              aria-labelledby="tab-web"
+            >
+              <p>
+                <code>wss</code> on port <code>443</code>, same origin as this
+                page. No client install or bridge required.
+              </p>
+              <div class="cta">
+                <a class="primary" href="/webclient/">Launch Web Client</a>
+              </div>
+            </div>
+
+            <div
+              class="panel"
+              id="panel-weechat"
+              role="tabpanel"
+              aria-labelledby="tab-weechat"
+            >
+              <p>
+                Connect over <code>wss</code> (port <code>443</code>) using the
+                snippet below, or directly over <code>irc+tls</code> on port
+                <code>6697</code> when the TCP+TLS surface is deployed.
+              </p>
+              <pre><code>/server add ircd irc.example.com/443
+/set irc.server.ircd.ssl on
+/connect ircd
+/join #test</code></pre>
+              <p class="note">
+                For the <code>irc+tls :6697</code> path, swap the port above for
+                <code>6697</code>. The TCP surface is a separate deployment
+                (Cloudflare Spectrum + Container); see the
+                <a
+                  href="https://gitea.com/ServerlessIRCd/ServerlessIRCd/wiki/Cloudflare-TCP-Deployment"
+                  >Cloudflare TCP Deployment Guide</a
+                >.
+              </p>
+            </div>
+
+            <div
+              class="panel"
+              id="panel-hexchat"
+              role="tabpanel"
+              aria-labelledby="tab-hexchat"
+            >
+              <p>
+                These TCP-only IRC clients do not support WebSocket natively.
+                Use <code>tools/tcp-ws-forwarder</code> to bridge them: it
+                listens on a local TCP port and forwards each IRC line over
+                <code>wss</code> to the Worker, negotiating the
+                <code>binary.ircv3.net</code> subprotocol upstream.
+              </p>
+              <pre><code>pnpm --filter tcp-ws-forwarder start \
+  --target wss://irc.example.com/ --listen-port 16667</code></pre>
+              <p class="note">
+                Then point HexChat / irssi at <code>127.0.0.1:16667</code>
+                (TLS off &mdash; the bridge is local). Bridging instructions
+                are in the
+                <a
+                  href="https://gitea.com/ServerlessIRCd/ServerlessIRCd/wiki/WebClientGuide"
+                  >Web Client Guide</a
+                >.
+              </p>
+            </div>
+
+            <div
+              class="panel"
+              id="panel-irccloud"
+              role="tabpanel"
+              aria-labelledby="tab-irccloud"
+            >
+              <p>
+                Both support WebSocket natively. Add a network pointing at
+                <code>wss://irc.example.com/</code> (port <code>443</code>, TLS
+                on); no bridge required.
+              </p>
+            </div>
+          </div>
+        </section>
+
         <div class="links">
+          <a href="/docs/">Docs</a>
           <a href="https://gitea.com/ServerlessIRCd/ServerlessIRCd">Source Code (Gitea)</a>
           <a href="https://gitea.com/ServerlessIRCd/ServerlessIRCd/issues">Issue Tracker</a>
           <a href="/webclient/">Web IRC Client</a>

package/apps/web/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@serverless-ircd/web",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "private": true,
   "description": "Web client workspace: Kiwi IRC SPA served at /webclient/ and project landing page at /",
   "license": "BSD-3-Clause",
   "type": "module",
   "scripts": {
     "build": "node scripts/build.mjs",
-    "build:staging": "node scripts/build.mjs --env staging",
     "build:prod": "node scripts/build.mjs --env prod",
+    "build:prod-aws": "node scripts/build.mjs --env prod-aws",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",
@@ -21,6 +21,7 @@
   "devDependencies": {
     "@types/node": "^26.1.1",
     "@vitest/coverage-v8": "^4.1.0",
+    "marked": "^18.0.9",
     "rimraf": "^6.0.0",
     "typescript": "^5.6.0",
     "vitest": "^4.1.0"

package/apps/web/scripts/build.mjs

@@ -3,14 +3,24 @@ import { existsSync } from 'node:fs';
 import { cp, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { resolveConfigFile } from '../src/build-env.ts';
+import {
+  hasUnsubstitutedPlaceholder,
+  parseApiUrlForKiwi,
+  resolveApiUrl,
+  resolveConfigFile,
+} from '../src/build-env.ts';
 import { parseKiwiConfig } from '../src/config-schema.ts';
+import { buildDocs } from '../src/render-docs.ts';
 
 const pkgRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const upstream = path.resolve(pkgRoot, 'upstream');
 const dist = path.resolve(pkgRoot, 'dist');
 const appDist = path.join(dist, 'webclient');
 const staticDir = path.join(pkgRoot, 'static');
+// The `docs/` submodule lives at the monorepo root (two levels up from
+// apps/web). Rendered to dist/docs/ by the docs build step (see step 6).
+const docsSrc = path.resolve(pkgRoot, '..', '..', 'docs');
+const docsDist = path.join(dist, 'docs');
 
 // The SPA is served at /webclient/ on the Worker (the [assets] binding serves
 // `dist/`). All hashed asset URLs must be /webclient/-prefixed so they load
@@ -44,6 +54,16 @@ if (!existsSync(upstream)) {
   );
 }
 
+// The `docs/` submodule must be checked out — step 6 renders every docs/*.md
+// to dist/docs/. Mirrors the Kiwi upstream guard above so a stale/partial
+// submodule checkout fails loudly with the recovery command instead of
+// producing an empty docs/ section on the deployed site.
+if (!existsSync(docsSrc)) {
+  throw new Error(
+    `Docs submodule missing at ${docsSrc}. Run \`git submodule update --init docs\` first.`,
+  );
+}
+
 // 1. Install upstream deps. Kiwi ships a yarn.lock; --frozen-lockfile gives a
 //    reproducible tree. Contributors get yarn via `corepack enable`. The
 //    guard checks for the actual binary the build invokes, not just the
@@ -92,11 +112,12 @@ await writeFile(indexDest, indexHtml);
 //    so missing fields, out-of-range ports, and non-`#` channels abort the
 //    build here with a readable error. The validated JSON is re-serialised
 //    (stable key order) so the baked config is identical to the schema output.
-const { file: configFileName, env: configEnv } = resolveConfigFile(process.argv.slice(2));
+const argv = process.argv.slice(2);
+const { file: configFileName, env: configEnv } = resolveConfigFile(argv);
 const configSrcPath = path.join(staticDir, configFileName);
 if (!existsSync(configSrcPath)) {
   throw new Error(
-    `Config file for env "${configEnv}" not found at ${configSrcPath}. Expected one of: config.json, config.staging.json, config.prod.json.`,
+    `Config file for env "${configEnv}" not found at ${configSrcPath}. Expected one of: config.json, config.prod.json, config.prod-aws.json.`,
   );
 }
 const configRaw = await readFile(configSrcPath, 'utf8');
@@ -108,6 +129,50 @@ try {
   // offending env config, not just the schema path.
   throw new Error(`${configFileName}: ${err.message}`, { cause: err });
 }
+
+// 4b. AWS deploy pipeline override: `--api-url <wss-url>` (read from the
+//     deployed stack's `ConnectUrl` CloudFormation output by
+//     `scripts/deploy-web-aws.mjs`) replaces the templated `server` value
+//     baked into `config.prod-aws.json` with the real API Gateway
+//     WebSocket host. No concrete URLs in the repo; substitution happens
+//     at deploy time.
+//
+//     irc-framework builds the WS URL as `wss://<server>:<port><direct_path>`,
+//     prepending `wss://` itself whenever `tls: true`. The override MUST
+//     split the URL into a hostname-only `server` and a stage-name
+//     `direct_path` (e.g. `/prod`) — assigning the full `wss://...` URL to
+//     `server` would make irc-framework prepend a second `wss://`,
+//     producing the malformed `wss://wss//<host>...` URL that Firefox
+//     rejects. When the flag is absent (Cloudflare deploys, local dev)
+//     the config's `server`/`direct_path` fields are left untouched.
+const apiUrlOverride = resolveApiUrl(argv);
+if (apiUrlOverride !== undefined) {
+  const { server, directPath } = parseApiUrlForKiwi(apiUrlOverride);
+  configParsed.startupOptions.server = server;
+  if (directPath !== undefined) {
+    configParsed.startupOptions.direct_path = directPath;
+  }
+}
+
+// 4c. Reject unsubstituted AWS deploy-time placeholders — but ONLY when
+//     the selected config is the prod-aws env. The prod-aws config carries
+//     `{{API_ID}}`/`{{REGION}}`/`{{STAGE}}` that MUST be substituted by the
+//     deploy pipeline via `--api-url`; a baked prod-aws build that left
+//     them in place would ship a broken SPA dialling a literal `{{API_ID}}...`
+//     URL.
+//
+//     The CF envs (`default`, `prod`) use Kiwi's runtime templates
+//     (`{{hostname}}`, `{{port}}`) which are resolved in the browser at
+//     load time and must survive the bake. Applying the guard to them
+//     would break every default `pnpm build` and every `build:prod`, so
+//     the helper scopes the check to non-CF envs. See
+//     `hasUnsubstitutedPlaceholder` in `src/build-env.ts`.
+if (hasUnsubstitutedPlaceholder(JSON.stringify(configParsed), configEnv)) {
+  throw new Error(
+    `Refusing to bake ${configFileName} with unsubstituted {{...}} placeholders. Pass --api-url <wss-url> (the deployed stack's ConnectUrl output) to substitute the API Gateway WebSocket URL.`,
+  );
+}
+
 await writeFile(
   path.join(appDist, 'static', 'config.json'),
   `${JSON.stringify(configParsed, null, 2)}\n`,
@@ -116,8 +181,13 @@ await writeFile(
 
 // 5. Landing page: copy the static landing page (landing/index.html) to
 //    dist/index.html so the Worker `[assets]` binding serves it at `/`. Pure
-//    static HTML + inline CSS (no JS); links to /webclient/ (the SPA), docs/,
-//    and the source repo.
+//    static HTML + inline CSS (no JS); links to /webclient/ (the SPA),
+//    /docs/ (the rendered docs built in step 6), and the source repo.
+//    Also copies landing/favicon.ico → dist/favicon.ico so both platforms
+//    (CF [assets] binding and AWS `s3 sync apps/web/dist`) serve the
+//    project-front-door icon at /favicon.ico. The Kiwi SPA has its own
+//    icon at /webclient/static/favicon.png (a Kiwi-upstream asset, copied
+//    in step 3); this one is for the landing page only.
 await mkdir(dist, { recursive: true });
 const landingSrc = path.join(pkgRoot, 'landing', 'index.html');
 if (!existsSync(landingSrc)) {
@@ -126,7 +196,22 @@ if (!existsSync(landingSrc)) {
   );
 }
 await cp(landingSrc, path.join(dist, 'index.html'));
+const faviconSrc = path.join(pkgRoot, 'landing', 'favicon.ico');
+if (!existsSync(faviconSrc)) {
+  throw new Error(
+    `Landing page favicon missing at ${faviconSrc}. Expected apps/web/landing/favicon.ico.`,
+  );
+}
+await cp(faviconSrc, path.join(dist, 'favicon.ico'));
+
+// 6. Docs: render every docs/*.md to standalone HTML under dist/docs/ so the
+//    Worker `[assets]` binding serves them at /docs/<name>.html (and /docs/
+//    for the index — Home.md becomes index.html). Requires the `docs/`
+//    submodule (guarded at step 0). Zero Worker changes — the existing
+//    [assets] binding already serves dist/ with not_found_handling = "none".
+const docsResult = await buildDocs({ srcDir: docsSrc, outDir: docsDist });
 
 console.log(
-  `Kiwi SPA built -> dist/webclient/ (publicPath=${PUBLIC_PATH}, config=${configFileName}, env=${configEnv})`,
+  `Kiwi SPA built -> dist/webclient/ (publicPath=${PUBLIC_PATH}, config=${configFileName}, env=${configEnv}, apiUrl=${apiUrlOverride === undefined ? 'from-config' : 'overridden'})`,
 );
+console.log(`Docs rendered -> dist/docs/ (${docsResult.emitted.length} pages, index=index.html)`);