feat(setup): support operator contact domain

Author: bhdicaire

defaults/v8s-site-config.json

@@ -15,6 +15,7 @@
   "operator": {
     "legal_name": "",
     "short_domain": "",
+    "operator_domain": "",
     "jurisdiction": "",
     "governing_law": "",
     "contact_email": "",

docs/adr/0002-site-config-schema-versioning.md

@@ -16,6 +16,8 @@ Keep `schema_version` at `1.0` for additive, backward-compatible changes.
 
 Increment `schema_version` only when a stored `custom/v8s-site-config.json` file needs a migration or when existing field semantics change incompatibly.
 
+Record additive field changes in `docs/schema-changelog.md`, even when `schema_version` does not change.
+
 When `schema_version` changes, the same change should include:
 
 - the new default schema version in `defaults/v8s-site-config.json`

docs/adr/0003-keep-instance-changes-in-custom.md

@@ -0,0 +1,28 @@
+# 0003. Keep instance-owned changes in custom
+
+Date: 2026-05-26
+
+Status: Accepted
+
+## Context
+
+vanityURLs instances need to receive product updates without overwriting local links, policies, branding, and operator settings.
+
+The repository contains product-owned defaults and scripts, instance-owned custom files, and generated build output.
+
+## Decision
+
+Product-owned files live under `defaults/` and `scripts/`.
+
+Instance-owned files live under `custom/`.
+
+Generated output lives under `build/` and `src/`.
+
+The build copies product defaults, overlays `custom/`, then writes generated runtime artifacts. Instance owners should edit `custom/`, not `defaults/` or `build/`, unless they are contributing product changes upstream.
+
+## Consequences
+
+- Instances can upgrade product files while preserving local configuration
+- `custom/` is the operational boundary for links, policies, site config, public overrides, and local helper settings
+- Build output can be deleted and regenerated
+- Documentation can refer to source files without turning generated artifacts into edit targets

docs/adr/0004-custom-policy-replaces-default-policy.md

@@ -0,0 +1,26 @@
+# 0004. Custom policy replaces the default source policy
+
+Date: 2026-05-26
+
+Status: Accepted
+
+## Context
+
+`v8s-policies.json` controls destination safety, allow domains, blocked domains, scanner keywords, and generated blocklist sources.
+
+If a custom policy were merged over the default source policy, a removed local policy item could reappear from the product defaults after an upgrade.
+
+## Decision
+
+When `custom/v8s-policies.json` exists, it replaces the default source policy.
+
+Generated feed data may still be merged afterward, and allow-domain entries can force-allow generated blocks.
+
+Legacy `v8s-blocklist.json` paths remain migration-compatible, but new product and instance documentation should use `v8s-policies.json`.
+
+## Consequences
+
+- Instance owners have explicit control over local policy
+- Removing a local policy entry is durable
+- Product defaults remain useful for new instances
+- Generated feeds remain a separate optional layer

docs/adr/0005-support-deferred-legal-pages.md

@@ -0,0 +1,28 @@
+# 0005. Support deferred legal pages
+
+Date: 2026-05-26
+
+Status: Accepted
+
+## Context
+
+New users need a fast phase-1 path to get a redirector online. Full privacy, terms, and standalone security pages require operator-specific legal decisions that may take longer.
+
+At the same time, a public short-link domain still needs abuse and vulnerability contact paths early.
+
+## Decision
+
+Setup supports deferring full privacy, terms, and standalone security pages with `operator.legal_pages_enabled`.
+
+When full legal pages are deferred:
+
+- Trust & Safety still deploys
+- `/.well-known/security.txt` still deploys when security contact data is valid
+- privacy, terms, and standalone security pages are skipped until configured
+
+## Consequences
+
+- Quickstart remains focused on first deployment
+- Operators can publish basic trust contact paths before finishing full legal review
+- Full legal pages still require operator, jurisdiction, contact, and date fields
+- Setup can be rerun later to enable the full page set

docs/adr/0006-use-readable-random-slugs.md

@@ -0,0 +1,29 @@
+# 0006. Use readable random slugs
+
+Date: 2026-05-26
+
+Status: Accepted
+
+## Context
+
+The `lnk` CLI can generate short slugs when the user does not provide one. Fully unrestricted random strings can include characters that are visually ambiguous or awkward to read over the phone.
+
+Different teams may also want different generated slug lengths for different tags.
+
+## Decision
+
+Generated slugs use a readable alphabet from `custom/v8s-site-config.json`, falling back to the product default.
+
+The site config also stores:
+
+- `links.random_slug_length`
+- `links.random_slug_alphabet`
+- `links.tag_random_slug_lengths`
+
+When multiple tags define random slug lengths, `lnk` uses the shortest configured length.
+
+## Consequences
+
+- Generated slugs are easier to read and type
+- Instances can keep short defaults while using longer slugs for selected tags
+- The schema fields are additive and do not require a `schema_version` bump

docs/adr/0007-scope-scanner-keywords-to-requests.md

@@ -0,0 +1,24 @@
+# 0007. Scope scanner keywords to requests
+
+Date: 2026-05-26
+
+Status: Accepted
+
+## Context
+
+The policy layer blocks scanner probes such as WordPress and PHP endpoint scans. Some strings, such as `.php`, are unsafe as requested paths on a non-PHP redirector but can be legitimate in long-link destinations.
+
+Blocking those strings everywhere can reject valid redirects.
+
+## Decision
+
+Scanner-probe keywords default to request scope unless explicitly configured otherwise.
+
+Policy entries can set `scope` to control whether a keyword applies to request paths, redirect targets, or both.
+
+## Consequences
+
+- Scanner probes are still blocked before short-link lookup
+- Valid long URLs ending in `.php` can be used as redirect targets
+- Existing scanner policies remain compatible
+- Policy authors can still opt into target blocking for specific keywords

docs/adr/0008-detach-and-upgrade-product-files.md

@@ -0,0 +1,24 @@
+# 0008. Detach instances and upgrade product files
+
+Date: 2026-05-26
+
+Status: Accepted
+
+## Context
+
+Users create their own instance repository from the vanityURLs code. That repository should become theirs, with its own GitHub remote, while still being able to refresh product files from upstream.
+
+## Decision
+
+`npm run detach` removes upstream project metadata that should not belong to a new instance.
+
+`npm run upgrade` refreshes product-owned paths from upstream while protecting instance-owned paths such as `custom/`, `wrangler.toml`, and `.dev.vars`.
+
+The default upgrade path includes product files such as `defaults/`, `scripts/`, `package.json`, `package-lock.json`, `README.md`, `LICENSE`, and `cloudflare-setup.md`.
+
+## Consequences
+
+- New instances can start as independent repositories
+- Upgrades can refresh product behavior without overwriting local configuration
+- Protected local paths remain the operator's responsibility
+- Release metadata and upstream workflow files do not leak into detached instances

docs/schema-changelog.md

@@ -0,0 +1,115 @@
+# Schema changelog
+
+This changelog records field-level schema changes for vanityURLs configuration files, including additive changes that do not bump `schema_version`.
+
+`schema_version` is reserved for incompatible stored-config changes that need migration. See `docs/adr/0002-site-config-schema-versioning.md`.
+
+## 2026-05-26
+
+### v8s-site-config.json
+
+Added optional field under `operator`:
+
+- `operator_domain`
+
+Compatibility: additive, no `schema_version` bump
+
+Migration: none required. When `operator.operator_domain` is blank or absent, setup defaults role-based email addresses from the short domain. When it is set, setup defaults operator, privacy, Trust & Safety, and security email addresses from the operator domain.
+
+### v8s-site-config.json
+
+Added optional fields under `links`:
+
+- `random_slug_length`
+- `random_slug_alphabet`
+- `tag_random_slug_lengths`
+
+Compatibility: additive, no `schema_version` bump
+
+Migration: none required. `lnk` reads missing values from `defaults/v8s-site-config.json`.
+
+### v8s-site-config.json
+
+Added installer-managed branding fields:
+
+- `branding.domain`
+- `branding.custom_public`
+- `branding.wordmark.black`
+- `branding.wordmark.green`
+
+Compatibility: additive, no `schema_version` bump
+
+Migration: none required. Existing instances without `branding` continue to use default public assets or custom public files.
+
+### v8s-site-config.json
+
+Added deferred legal-page mode:
+
+- `operator.legal_pages_enabled`
+
+Compatibility: additive, no `schema_version` bump
+
+Migration: none required. Missing values behave like enabled legal pages only when the operator fields are fully configured.
+
+### v8s-site-config.json
+
+Expanded operator fields used by generated privacy, terms, Trust & Safety, security, and `security.txt` output:
+
+- `operator.legal_name`
+- `operator.short_domain`
+- `operator.jurisdiction`
+- `operator.governing_law`
+- `operator.contact_email`
+- `operator.privacy_contact`
+- `operator.abuse_contact`
+- `operator.security_contact`
+- `operator.last_updated`
+- `operator.umami_geo_ip_mode`
+- `operator.analytics_disclosure`
+- `operator.analytics_retention`
+- `operator.abuse_response_window`
+
+Compatibility: additive, no `schema_version` bump
+
+Migration: none required for plain redirect behavior. Generated legal pages require the relevant fields before launch.
+
+### v8s-local-config.json
+
+Added local helper and local publish configuration:
+
+- `shell_helper`
+- `lnk_cli`
+- `local_publish`
+- `registry`
+- `repository`
+
+Compatibility: additive, no `schema_version` bump
+
+Migration: none required. `npm run local-install` writes workstation-specific values.
+
+### v8s-policies.json
+
+Replaced legacy blocklist naming with the broader policy source:
+
+- `defaults`
+- `allow_domains`
+- `blocked_keywords`
+- `block_domains`
+- optional `generated_sources`
+
+Compatibility: additive and rename-compatible, no `schema_version` bump
+
+Migration: legacy `v8s-blocklist.json` filenames are still recognized for migration compatibility, but new instances should use `v8s-policies.json`.
+
+### v8s-schedules.json
+
+Added schedule configuration keyed by slug:
+
+- `timezone`
+- `default`
+- shortcut rules such as `9to5`
+- `rules[]` entries with `label`, `timezone`, `days`, `from`, `to`, and `target`
+
+Compatibility: additive, no `schema_version` bump
+
+Migration: none required. Missing custom schedules mean the link uses its normal target.

scripts/install.mjs

@@ -91,20 +91,22 @@ async function promptForMissing(args) {
     args.configureLegalPages = await confirm(rl, "Configure privacy, terms, and security pages now?", configuredOperator.legal_pages_enabled !== false && hasConfiguredLegalPages(configuredOperator));
     args.operatorLegalName = await question(rl, "Operator legal name", args.operatorLegalName || configuredOperator.legal_name || "");
     args.operatorShortDomain = args.operatorShortDomain || args.domain;
+    args.operatorDomain = await question(rl, "Operator domain for contact emails", args.operatorDomain || configuredOperator.operator_domain || "");
+    const operatorEmailDomain = args.operatorDomain || args.domain;
     if (args.configureLegalPages) {
       args.operatorJurisdiction = await question(rl, "Operator jurisdiction, for example Canada", args.operatorJurisdiction || configuredOperator.jurisdiction || "");
       args.operatorGoverningLaw = await question(rl, "Governing law", args.operatorGoverningLaw || configuredOperator.governing_law || args.operatorJurisdiction || "");
-      args.operatorContactEmail = await question(rl, "Operator contact email", args.operatorContactEmail || configuredOperator.contact_email || defaultContactEmail("hello", args.domain));
-      args.operatorPrivacyContact = await question(rl, "Privacy contact", args.operatorPrivacyContact || configuredOperator.privacy_contact || defaultContactEmail("privacy", args.domain));
+      args.operatorContactEmail = await question(rl, "Operator contact email", args.operatorContactEmail || configuredOperator.contact_email || defaultContactEmail("hello", operatorEmailDomain));
+      args.operatorPrivacyContact = await question(rl, "Privacy contact", args.operatorPrivacyContact || configuredOperator.privacy_contact || defaultContactEmail("privacy", operatorEmailDomain));
     } else {
       args.operatorJurisdiction = args.operatorJurisdiction || configuredOperator.jurisdiction || "";
       args.operatorGoverningLaw = args.operatorGoverningLaw || configuredOperator.governing_law || args.operatorJurisdiction || "";
       args.operatorContactEmail = args.operatorContactEmail || configuredOperator.contact_email || "";
       args.operatorPrivacyContact = args.operatorPrivacyContact || configuredOperator.privacy_contact || "";
     }
-    args.operatorAbuseContact = await question(rl, "Trust & Safety contact", args.operatorAbuseContact || configuredOperator.abuse_contact || defaultContactEmail("abuse", args.domain));
+    args.operatorAbuseContact = await question(rl, "Trust & Safety contact", args.operatorAbuseContact || configuredOperator.abuse_contact || defaultContactEmail("abuse", operatorEmailDomain));
     args.operatorAbuseResponseWindow = await question(rl, "Trust & Safety response window", args.operatorAbuseResponseWindow || configuredOperator.abuse_response_window || "5 business days");
-    args.operatorSecurityContact = await question(rl, "Security contact", args.operatorSecurityContact || configuredOperator.security_contact || defaultContactEmail("security", args.domain));
+    args.operatorSecurityContact = await question(rl, "Security contact", args.operatorSecurityContact || configuredOperator.security_contact || defaultContactEmail("security", operatorEmailDomain));
     if (args.configureLegalPages) {
       args.operatorLastUpdated = await question(rl, "Legal pages last updated date", args.operatorLastUpdated || configuredOperator.last_updated || gitLastUpdatedDate() || todayIsoDate());
     } else {
@@ -292,14 +294,17 @@ function normalizeWordmarkSplit(args) {
 }
 
 function normalizeOperator(args) {
-  const contactEmail = String(args.operatorContactEmail || defaultContactEmail("hello", args.domain)).trim();
-  const privacyContact = String(args.operatorPrivacyContact || defaultContactEmail("privacy", args.domain)).trim();
-  const abuseContact = String(args.operatorAbuseContact || defaultContactEmail("abuse", args.domain)).trim();
-  const securityContact = String(args.operatorSecurityContact || defaultContactEmail("security", args.domain)).trim();
+  const operatorDomain = normalizeDomain(args.operatorDomain || "");
+  const emailDomain = operatorDomain || args.domain;
+  const contactEmail = String(args.operatorContactEmail || defaultContactEmail("hello", emailDomain)).trim();
+  const privacyContact = String(args.operatorPrivacyContact || defaultContactEmail("privacy", emailDomain)).trim();
+  const abuseContact = String(args.operatorAbuseContact || defaultContactEmail("abuse", emailDomain)).trim();
+  const securityContact = String(args.operatorSecurityContact || defaultContactEmail("security", emailDomain)).trim();
 
   return {
     legal_name: String(args.operatorLegalName || "").trim(),
     short_domain: normalizeDomain(args.operatorShortDomain || args.domain),
+    operator_domain: operatorDomain,
     jurisdiction: String(args.operatorJurisdiction || "").trim(),
     governing_law: String(args.operatorGoverningLaw || args.operatorJurisdiction || "").trim(),
     contact_email: contactEmail,