Add Shortwave link-shortener example

.github/workflows/shortwave.yml

@@ -0,0 +1,38 @@
+name: Shortwave checks
+
+on:
+  pull_request:
+    paths:
+      - 'applications/shortwave/**'
+      - '.github/workflows/shortwave.yml'
+  push:
+    branches: [main]
+    paths:
+      - 'applications/shortwave/**'
+      - '.github/workflows/shortwave.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: applications/shortwave
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22.23.2
+          cache: npm
+          cache-dependency-path: applications/shortwave/package-lock.json
+      - run: npm ci
+      - run: npm test
+      - run: npm run types:workers
+      - run: npm run typecheck
+      - run: npm run build:workers
+      - run: npx wrangler deploy --dry-run
+
+# Live Cloud and browser acceptance is a separate, explicitly configured run.

README.md

@@ -64,13 +64,14 @@ ClickHouse ships official client libraries for [C# / .NET](https://clickhouse.co
 - [Provision a database for a TypeScript application](./applications/report-history/README.md): Use `clickhousectl` to create the Cloud service for a report-history application.
 - [Investigate and resolve a latency SLA breach](./ai/clickhousectl/agentic-sla-scaling/README.md): Give an agent access to `clickhousectl` to inspect a live service and apply a scaling change.
 
-### Postgres managed by ClickHouse: transactions alongside analytics
+### ClickHouse Managed Postgres: transactions alongside analytics
 
-[Postgres managed by ClickHouse](https://clickhouse.com/cloud/postgres) is a managed PostgreSQL service in ClickHouse Cloud for transactional applications, with native integration into ClickHouse for analytics. Use Postgres for application records and transactions, then replicate changes to ClickHouse for reporting and aggregation.
+[ClickHouse Managed Postgres](https://clickhouse.com/cloud/postgres) is a managed PostgreSQL service in ClickHouse Cloud for transactional applications, with native integration into ClickHouse for analytics. Use Postgres for application records and transactions, then replicate changes to ClickHouse for reporting and aggregation.
 
 [ClickPipes](https://clickhouse.com/cloud/clickpipes) provides managed ingestion into ClickHouse Cloud, including Postgres change data capture (CDC), streaming sources, and object storage.
 
-- [Postgres-to-ClickHouse data modeling](./postgresql-clickhouse-data-modeling/README.md): Replicate a tiny fixture from PostgreSQL to ClickHouse with PeerDB, then verify inserts, updates, and deletes. Follow the separate managed Postgres and ClickPipes walkthrough for ClickHouse Cloud; a larger Stack Overflow import is optional.
+- [Shortwave link shortener](./applications/shortwave/README.md): Build and deploy a link shortener using ClickHouse Managed Postgres for application data, ClickPipes for metadata sync, and ClickHouse for click analytics.
+- [Postgres-to-ClickHouse data modeling](./postgresql-clickhouse-data-modeling/README.md): Replicate a tiny fixture from PostgreSQL to ClickHouse with PeerDB, then verify inserts, updates, and deletes. Follow the separate ClickHouse Managed Postgres and ClickPipes walkthrough for ClickHouse Cloud; a larger Stack Overflow import is optional.
 
 ### ClickStack: logs, metrics, traces, and session replay
 
@@ -108,7 +109,7 @@ Browse [all local analytics examples](./local-analytics/README.md) for more file
 
 | Directory | What you'll find |
 | --- | --- |
-| [applications](./applications/) | Application examples, including report results and run history with ClickHouse Cloud. |
+| [applications](./applications/) | Application examples: a link shortener, report results, and run history with ClickHouse Cloud. |
 | [ai](./ai/README.md) | AI agents, MCP integrations, and workflows using `clickhousectl`. |
 | [blog-examples](./blog-examples/) | Code and resources accompanying the [ClickHouse Blog](https://clickhouse.com/blog). |
 | [clickstack](./clickstack/) | Observability examples for LLM applications and MCP servers. |

applications/shortwave/.env.example

@@ -0,0 +1,26 @@
+# Local application runtime against your ClickHouse Cloud deployment.
+# Copy to .env in your checkout. Never commit the populated file.
+VITE_CLERK_PUBLISHABLE_KEY=pk_test_replace_me
+CLERK_SECRET_KEY=sk_test_replace_me
+APP_URL=http://localhost:4317
+PORT=4317
+DATABASE_URL=postgresql://link_shortener_app:replace_me@replace-me.postgres.clickhouse.cloud:5432/postgres
+# Relative to the project directory; keep certificate verification enabled.
+PG_CA_CERT_PATH=.deployment/postgres-ca.pem
+CLICKHOUSE_URL=https://replace-me.clickhouse.cloud:8443
+CLICKHOUSE_DATABASE=link_shortener
+# Use the destination database recorded by ClickPipes setup.
+CLICKHOUSE_CDC_DATABASE=default
+CLICKHOUSE_USERNAME=link_shortener_app
+CLICKHOUSE_PASSWORD=replace_me
+# Comma-separated verified short hostnames attached to your deployed Worker.
+PUBLIC_CUSTOM_DOMAINS=
+
+# Optional hosted smoke checks. Set APP_URL to your deployed HTTPS application
+# origin and use a signed-in account that has verified SMOKE_CUSTOM_ORIGIN.
+# Keep that account UUID and the smoke receipt private.
+SMOKE_CUSTOM_ORIGIN=
+SMOKE_ACCOUNT_ID=
+
+# Cloud API keys belong in the CLI credential store; migration credentials belong
+# in .deployment/passwords.env. Never add either to this runtime environment.

applications/shortwave/.gitignore

@@ -0,0 +1,24 @@
+.env
+.env.*
+!.env.example
+node_modules/
+.output/
+.tanstack/
+dist/
+.vite/
+coverage/
+*.log
+.DS_Store
+.secrets/
+.deployment/
+.private/
+# clickhousectl can save Cloud credentials and Query API keys here.
+.clickhouse/
+.wrangler/
+.dev.vars
+.dev.vars.*
+*.pem
+test-results/
+playwright-report/
+playwright/.auth/
+playwright/.clerk/

applications/shortwave/AGENTS.md

@@ -0,0 +1,42 @@
+# Agent instructions
+
+## Project context
+
+- Shortwave is a link-shortener example; see the [deployment and release checklist](docs/v1-readiness.md). Cloudflare Workers is the implemented host. Keep local development in the isolated VM.
+- Start with [README.md](README.md); read the relevant brief, architecture, or setup document linked there. Keep proposals distinct from settled decisions.
+- Use TanStack, Click UI, and Clerk. Deploy both databases and ClickPipes in ClickHouse Cloud; use `clickhousectl` for Cloud provisioning and orchestration. Use Wrangler for Cloudflare resources. `pg_clickhouse` and ClickStack remain proposals.
+
+## Implementation and deployment contract
+
+- Keep deployer hostnames, resource IDs, personal paths, and credentials out of the public example. Generate configuration from explicit inputs; keep `.deployment`, `.private`, `.secrets`, environment files and credential-bearing logs private.
+- Document infrastructure as explicit `clickhousectl` and Wrangler commands in README and the hosting guide. Keep database setup in SQL files passed to the CLI; do not add JavaScript provisioning wrappers. Review inputs before creation and verify the built Worker config matches the recorded account, bindings and hostnames before deployment.
+- Postgres owns authorization and redirects. ClickPipes owns `cdc_links`; never apply the local metadata fixture to Cloud. Preserve CDC version/delete handling and event-ID deduplication across delivery retries.
+- Separate runtime, migration, and management credentials. Preserve TLS verification and account isolation. Reuse recorded resources on setup retries; reconcile ambiguous outcomes before retrying, and target cleanup by recorded IDs. Never delete a receipt to force recreation.
+- For assessments, deliver findings and acceptance criteria. For implementation requests, finish authorized work and verification; follow the user's scope over conflicting skill advice and identify concrete blockers.
+- Run relevant checks in the VM: `npm test`, `npm run typecheck`, and `npm run build:workers`. Live integration/browser checks require their documented Cloud fixtures. Report passed, skipped, and unverified checks separately; publication requires the fresh-deployment checklist.
+
+## Development sandbox
+
+- This VM workflow is for maintainer/agent development. Public deployment instructions assume CLI tools on the reader's laptop; see [maintainer environment](docs/maintainer-environment.md) for our setup.
+
+- Before installing dependencies or running application code, create a dedicated OrbStack Linux VM using the CLI. Reuse `link-shortener-dev` only after checking its isolation settings with `orb info`.
+
+  ```sh
+  orb list
+  orb create --isolated --isolate-network ubuntu:noble link-shortener-dev
+  orb info link-shortener-dev
+  orb -m link-shortener-dev -w /home sh -lc 'mkdir -p "$HOME/link-shortener"'
+  orb -m link-shortener-dev -w /home sh -lc 'cd "$HOME/link-shortener" && <command>'
+  ```
+
+- Create only if absent; replace `<command>` with the intended command. Verify flags with installed CLI help if needed; do not silently fall back to an unisolated machine.
+- Copy source into the VM's own filesystem with `scripts/vm.sh push`. Use `scripts/install-tools.sh` inside Linux for the pinned tools; run dependency installs, development servers, builds and tests there. Keep caches, `node_modules` and build output inside the VM; databases remain in ClickHouse Cloud.
+- Keep host mounts, SSH-agent forwarding, host command execution, and host Docker sockets disabled. Transfer only project files and explicitly needed credentials; copy reviewed source changes back without generated files or secrets.
+- Host-side document/source editing, read-only inspection, and OrbStack management are fine. Do not install project dependencies on macOS. Documentation-only tasks do not require starting a VM.
+
+## Keep changes reviewable
+
+- UI copy: use plain task names. Do not add promotional subtitles, taglines, or routine explanatory captions unless the user requests them. Helper text must resolve a concrete ambiguity or explain an actionable state; audit new visible strings before handover.
+- Update the relevant documentation when decisions change. Link to authoritative sources for platform claims; mark untested commands and unresolved assumptions.
+- For code changes, run appropriate checks inside the VM; report what passed and what remains unverified. For documentation, check links and consistency. See README for build, typecheck, and test commands.
+- Keep this file short and operational. Put architecture, setup walkthroughs, and task history in `docs/`, not here.

applications/shortwave/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md