Reference on vanityURLs

Analytics

Mon, 01 Jan 0001 00:00:00 +0000

vanityURLs analytics runs inside the Cloudflare Worker. It does not require browser tracking JavaScript, cookies, or a visitor account.

Cloudflare Web Analytics and Real User Measurement (RUM) are not part of the vanityURLs baseline. Leave Cloudflare RUM disabled unless an operator intentionally wants browser-side performance telemetry outside the redirector’s server-side event model.

The Worker sends analytics with ctx.waitUntil().¹ Redirects and pages should continue responding even when the analytics provider is slow or unavailable.

Brand

Mon, 01 Jan 0001 00:00:00 +0000

The vanityURLs brand standards now live at brand.vanityurls.link. Use that site for logo, color, typography, badge, product UI, and asset guidance.

Branding controls the public wordmark and the short line under generated public pages. These values live in custom/v8s-site-config.json and are applied at build time, so a normal branded instance does not need to copy default pages into custom/public/.

You can customize during npm run setup or by manually updating files in custom/.

Cheatsheet

Mon, 01 Jan 0001 00:00:00 +0000

Use this cheatsheet when you already know the product and need the shortest path to the next correct action. It is designed to work on screen and as a browser-generated PDF.

Daily workflow

Need	Action / file	Notes
Install deps	`npm install`	Run once after checkout or dependency changes.
Start locally	`npm run dev`	Runs the Worker through Wrangler for local testing.
Validate	`npm run check`	Builds and checks generated runtime artifacts before deploy.
Deploy	`git push`	GitHub and Cloudflare automation publish the Worker.

Repositories

Surface	Repository	Deploys to
Redirector	`vanityURLs/code`	`https://VanityURLs.link`
Documentation	`vanityURLs/website`	`https://www.VanityURLs.link`
Generated output	`build/`, `src/`	Do not edit directly.

Core files

File	Use	Owner
`custom/v8s-links.txt`	Human-authored redirect list.	Instance
`custom/v8s-site-config.json`	Branding, contacts, languages, timezone.	Instance
`custom/v8s-policies.json`	Allow domains, blocked domains, keyword policy.	Instance
`defaults/`	Product baseline copied or merged during build.	Product

Link row format

Field	Example	Notes
Slug	`docs`	Public path segment. Keep it readable and durable.
Target	`https://example.com/docs`	Destination URL after policy checks.
State	`active`	Controls whether the redirect should resolve.
Metadata	`title`, `owner`, `notes`	Helps review, audit, dashboard display, and handoff.

Schedules

Need	Syntax	Notes
Timed target	`@schedule`	Indent schedule blocks below the link row.
Timezone	`America/Toronto`	Use IANA timezone names accepted by the runtime.
Exact links	`/launch`	Schedules apply to exact links, not splat namespaces.
Fallback	Link row target	The normal target remains the default outside windows.

Redirect behavior

Input	Behavior	Check
Known active slug	Redirects to target.	Confirm target and policy allow it.
Inactive or expired slug	Shows the matching status page.	Review state, dates, and generated registry.
Blocked destination	Does not redirect.	Check policy source and generated blocklist.
Unknown path	Returns not-found handling.	Check slug spelling and generated routes.

Customize safely

Goal	Use	Avoid
Change links	`custom/v8s-links.txt`	Editing `build/v8s.json`.
Brand pages	`custom/v8s-site-config.json`	Copying full templates unless needed.
Override assets	`custom/public/`	Changing product defaults for one instance.
Change Worker code	`scripts/workers/`	Editing generated `src/`.

Troubleshooting

Symptom	Check	Likely fix
Works locally, not live	GitHub action and Worker deploy status.	Push, wait for deploy, then retest.
Link missing	Generated `build/v8s.json`.	Fix source row, then rebuild.
Wrong language page	Configured languages and localized overrides.	Add localized page or rely on fallback.
Schedule surprises	Operator timezone and date window.	Use explicit IANA timezone names.

Quick comparisons

Choice	Use this when	Remember
`defaults/`	You are changing the product baseline for every instance.	Review as product behavior.
`custom/`	You are changing one deployed instance.	Best place for operator-owned changes.
Exact slug	The public path must resolve to one known destination.	Supports schedule behavior.
Splat namespace	A stable prefix should forward nested paths.	Do not use for time-sensitive redirects.

Cloudflare products

Mon, 01 Jan 0001 00:00:00 +0000

vanityURLs is a URL shortener that runs on Cloudflare’s edge network with your own domain.

Product	Role in vanityURLs
Cloudflare DNS	Authoritative DNS for the short domain, including the proxied Worker custom domain record
Cloudflare Workers	Runtime for redirects, protected operational pages, generated static assets, and server-side analytics dispatch
Cloudflare Access	Zero Trust Network Access (ZTNA) protection for protected operational surfaces such as the Stats dashboard and Runtime test matrix
Cloudflare SSL/TLS	Edge certificates, Universal SSL, HTTPS enforcement, and minimum TLS configuration

Network protection before traffic reaches the vanityURLs instance

Product or surface	Role in vanityURLs
Web Application Firewall	Custom security rules for scanner probes, unexpected methods, suspicious clients, unwanted AI crawlers, and other edge-blocked traffic
Cloudflare Rate Limiting	Rate limiting for abuse patterns that should not spend Worker resources
Distributed Denial-of-Service (DDoS) Protection	Always-on network protection
Cloudflare Bot Management	Bot controls used to reduce automated abuse before requests reach the Worker
Cloudflare AI Crawl Control	Crawler-specific controls for selected AI crawler families
Cloudflare Rules	Managed Transforms and URL normalization before traffic reaches the vanityURLs instance
Cloudflare Security Events	Review surface for mitigations applied before the Worker runs

Cloudflare is an evergreen SaaS platform: features, APIs, dashboard labels, and navigation can change continuously without major version numbers. To keep the documentation aligned with that moving surface, vanityURLs maintains a structured Cloudflare dashboard capture in JSON. The capture helps maintainers compare UI changes over time and update the documentation deliberately. For the maintenance rationale, see ADR 0012 and The JSON audit ledger behind the Cloudflare setup docs.

Configuration files

Mon, 01 Jan 0001 00:00:00 +0000

vanityURLs keeps product defaults, instance-owned choices, local workstation settings, and generated runtime artifacts in separate files.

Use this page to identify the current configuration files and the schema shape each one follows. The exact implementation contract remains the Git files and scripts in the code repository.

Source configuration

File	Format	Schema shape	Owner
`wrangler.toml`	TOML, following Cloudflare Wrangler configuration	`name`, `main`, `compatibility_date`, `workers_dev`, `preview_urls`, `[build]`, `[assets]`, `[vars]`, `[[routes]]`, `[observability]`	Instance
`package.json`	npm package manifest JSON	`scripts`, `devDependencies`, package metadata	Product
`package-lock.json`	npm lockfile JSON	Locked dependency graph generated by npm	Product
`defaults/v8s-site-config.json`	vanityURLs site config JSON, `schema_version: "1.0"`	Product baseline for `i18n`, `links`, and `operator`	Product
`custom/v8s-site-config.json`	vanityURLs site config JSON, `schema_version: "1.0"`	Instance overrides for `i18n`, `links`, `operator`, and `branding`; `operator.operator_domain` can drive default contact email domains	Instance
`defaults/v8s-links.txt`	Pipe-delimited text with optional inline `@schedule` blocks	`slug\|target\|state\|title\|description\|tags\|owner\|expires_at\|notes`, followed by indented schedule directives when needed	Product starter links
`custom/v8s-links.txt`	Pipe-delimited text with optional inline `@schedule` blocks	Same as `defaults/v8s-links.txt`; this is the human-authored source of truth for links	Instance
`custom/v8s-schedules.json`	Legacy vanityURLs schedule JSON	Deprecated 3.x compatibility source read by the build and current `lnk schedule` command; inline `@schedule` blocks take precedence	Instance
`defaults/v8s-policies.json`	vanityURLs policy JSON, `schema_version: "1.0"`	`defaults`, `allow_domains`, `blocked_keywords`, `block_domains`, optional `generated_sources`	Product
`custom/v8s-policies.json`	vanityURLs policy JSON, `schema_version: "1.0"`	Same as `defaults/v8s-policies.json`; custom policy replaces the default source policy before generated feeds are merged	Instance
`defaults/v8s-blocklist-categories.json`	vanityURLs policy taxonomy JSON, `schema_version: "1.0"`	`categories`, `severities`, `sources`	Product
`custom/v8s-blocklist-categories.json`	vanityURLs policy taxonomy JSON, `schema_version: "1.0"`	Optional custom extension or override for generated blocklist categories, severities, and sources	Instance
`defaults/v8s-language-metadata.json`	vanityURLs language metadata JSON	Product labels for generated localized page lists and state-page navigation	Product
`defaults/legal/v8s-legal-content.json`	vanityURLs legal content JSON	Default legal-page, Trust & Safety, security, and response-window copy rendered by the build	Product
`defaults/v8s-local-config.json`	vanityURLs local helper JSON, `schema_version: "1.0"`	`shell_helper`, `lnk_cli`, `local_publish`, `registry`, `repository`	Product
`custom/v8s-local-config.json`	vanityURLs local helper JSON, `schema_version: "1.0"`	Workstation-specific helper paths and local publish settings written by `npm run local-install`	Workstation
`defaults/public/_headers`	Cloudflare static asset header rules	Path pattern followed by indented header lines	Product or instance overlay

Legacy blocklist filenames Changed in 3.0.0

Runtime registry

Mon, 01 Jan 0001 00:00:00 +0000

build/v8s.json is the generated runtime registry consumed by the Worker. Humans edit source files such as custom/v8s-links.txt; the build validates and compiles those files into this runtime shape.

Schema 3.0

Schema 3.0 is tree-first:

Field	Purpose
`schema_version`	Runtime registry contract version, currently `3.0`
`generated_at`	Build timestamp
`generated_timezone`	Operator timezone used by protected dashboards when displaying build time
`default_state`	Fallback lifecycle state, normally `permanent`
`routing`	State-to-outcome map used by the Worker
`tree`	Canonical nested lookup structure for runtime resolution
`links[]`	Compatibility array for dashboards, local helpers, and review workflows

Each tree node has a children object and may have a link. Each link keeps the same fields exposed in links[], including slug, match, target, state, metadata, and optional schedule.

Custom overrides

Mon, 01 Jan 0001 00:00:00 +0000

Use custom/ for instance-owned files. This keeps your deployment upgradable because default pages, Worker logic, source policy, and local helper settings can move forward without mixing in every local choice.

For the upgrade rationale, read Keeping vanityURLs upgradable with custom overrides. For the build order and generated artifacts, read Configuration files.

Defaults versus custom

defaults/ is the product baseline. custom/ is your instance overlay. Files in custom/ either replace specific defaults or provide instance data that should survive upstream updates.

Public and status pages

Mon, 01 Jan 0001 00:00:00 +0000

Use custom/public/ when an instance needs to replace generated public pages, add public assets, or customize link status pages. Use Custom overrides for the broader configuration-file map.

Public override map

Avoid replacing shared public assets casually

Glossary

Mon, 01 Jan 0001 00:00:00 +0000

The glossary defines the terms and abbreviations used on the web site.

Terms

Access application: A Cloudflare Zero Trust application that protects selected paths, such as localized stats paths like /en/_stats/ and /fr/_stats/, plus /_tests/*, before the Worker serves those pages.
Access policy: A Cloudflare Zero Trust rule that decides which identities can reach a protected Access application.
Alias: The short path or keyword used to reach a configured destination.
Badge: A compact visual link that advertises, previews, or shares an alias.
Block policy: The instance-owned rules in custom/v8s-policies.json that block unsafe domains, keywords, scanner paths, or unwanted traffic before redirect lookup.
Build artifact: A generated file under build/ or src/. Edit source files in custom/ or defaults/, then rebuild instead of editing artifacts directly.
Custom overlay: The instance-owned layer under custom/. It overrides or extends product defaults without editing upstream files.
Default target: The fallback destination used by a scheduled link when no time-based rule is currently active.
Destination: The long URL a short link redirects to. In the link format, it is stored in the target column.
Generated registry: The runtime redirect registry written to build/v8s.json during build from links, inline schedules, policies, and configuration.
Generated page: A page emitted by the redirector for expansion, fallback, link status, legal, privacy, or other public runtime surfaces.
Hardening: Reducing the available attack surface by disabling unused features, tightening browser policies, and keeping security controls owned by one clear source of truth.
Identity provider: A login source used by Cloudflare Access, such as GitHub, Google, or one-time PIN, to confirm who is trying to reach a protected page.
Idempotent: A command or operation that can be run repeatedly with the same inputs without creating duplicate state or requiring a fresh setup. In vanityURLs, npm run setup rereads existing answers and updates the same generated files.
IDNA: Internationalized Domain Names in Applications, the standard that lets software represent non-ASCII domain names in DNS-compatible ASCII form.
Link registry: The set of short-link records used by vanityURLs. Humans edit custom/v8s-links.txt; the build produces the generated registry consumed by the Worker.
Operator: The person, team, or organization responsible for the vanityURLs instance, public pages, trust contacts, and legal-page configuration.
Owner label: A short internal value in v8s-links.txt that identifies the person or team accountable for a link.
Punycode: The ASCII encoding used by IDNA for internationalized domain labels, usually visible with the xn-- prefix.
Random slug: A slug generated by lnk when you provide a destination but do not choose the short path yourself.
Redirect: A short-link request that resolves to a configured destination.
Route: The Cloudflare Workers mapping that sends requests for your short domain to the vanityURLs Worker.
Runtime: The Cloudflare Worker and static assets that serve redirects and pages after build and deployment.
Scheduled link: A short link whose destination can change by day, time window, and timezone using inline @schedule rules in v8s-links.txt.
Short domain: The domain used for redirects, such as v8s.link or go.example.com.
Slug: The path after your short domain. In https://v8s.link/docs, the slug is docs.
Splat link: A link stored as slug/* that forwards the remaining path into a destination containing :splat.
Tag: A comma-separated label on a link row used to group links, describe purpose, or select tag-specific random slug lengths.
Worker: The Cloudflare Workers application that runs the vanityURLs redirector.

Abbreviations

ADR ← Architecture Decision Record: A short document that records an implementation decision and the reason behind it.
API ← Application Programming Interface: A documented interface that software can call, such as an analytics or provider endpoint.
CLI ← Command Line Interface: A terminal command interface, such as the lnk helper used to manage links.
CI ← Continuous Integration: Automated checks that run before code is merged or deployed.
CSP ← Content Security Policy: Browser security rules that limit which scripts, styles, images, and connections a page may use.
DNS ← Domain Name System: The system that maps hostnames to network destinations and lets Cloudflare route your short domain.
GDPR ← General Data Protection Regulation: European Union privacy regulation that may affect operators handling personal data from EU visitors.
HTML ← HyperText Markup Language: The markup language used for web pages.
HTTP ← Hypertext Transfer Protocol: The protocol used by browsers, clients, and Workers to request and return web resources.
IP ← Internet Protocol: Network addressing used to route traffic; analytics and logs may include visitor IP addresses.
JSON ← JavaScript Object Notation: A structured data format used by vanityURLs for generated registries and configuration files.
OTP ← One-Time PIN: A temporary login code that Cloudflare Access can send directly to an approved email address.
QR ← Quick Response: A scannable barcode format often used to share short links in print or slides.
RFC ← Request for Comments: A standards-track or informational publication, such as RFC 9116 for security.txt.
SLA ← Service-Level Agreement: A formal service commitment; vanityURLs docs warn operators not to promise one casually.
SRI ← Subresource Integrity: A browser integrity check that lets HTML pin the expected hash of a loaded script or stylesheet.
TLS ← Transport Layer Security: The encryption protocol behind HTTPS.
URL ← Uniform Resource Locator: The address of a web resource, including the protocol, host, path, and optional query string.
UTM ← Urchin Tracking Module: Campaign query parameters used by analytics tools.
VDP ← Vulnerability Disclosure Policy: A policy that explains how security researchers should report vulnerabilities.
WAF ← Web Application Firewall: Cloudflare edge rules that block suspicious or abusive traffic before it reaches the Worker.
YAML ← YAML Ain't Markup Language: A human-readable structured data format used by the documentation site for data and configuration.

Timezones

Mon, 01 Jan 0001 00:00:00 +0000

vanityURLs accepts IANA timezone names, plus UTC. Do not enter numeric offsets such as -4, -5, or GMT-0400; offsets do not describe daylight saving time.

Use the place-based timezone that matches the operator or scheduled link. For example, Eastern Time should usually be America/Toronto or America/New_York. The JavaScript Intl timezone database handles the switch between EST and EDT.

Common choices

Region	Choices
UTC	`UTC`
Canada	`America/Toronto`, `America/Montreal`, `America/Halifax`, `America/Winnipeg`, `America/Regina`, `America/Edmonton`, `America/Vancouver`
United States	`America/New_York`, `America/Chicago`, `America/Denver`, `America/Phoenix`, `America/Los_Angeles`, `America/Anchorage`, `Pacific/Honolulu`
Europe	`Europe/London`, `Europe/Dublin`, `Europe/Paris`, `Europe/Berlin`, `Europe/Rome`, `Europe/Madrid`, `Europe/Amsterdam`, `Europe/Stockholm`, `Europe/Zurich`
Latin America	`America/Mexico_City`, `America/Bogota`, `America/Lima`, `America/Santiago`, `America/Argentina/Buenos_Aires`, `America/Sao_Paulo`
Africa and Middle East	`Africa/Casablanca`, `Africa/Johannesburg`, `Africa/Cairo`, `Asia/Jerusalem`, `Asia/Dubai`, `Asia/Riyadh`
Asia	`Asia/Kolkata`, `Asia/Bangkok`, `Asia/Singapore`, `Asia/Hong_Kong`, `Asia/Shanghai`, `Asia/Tokyo`, `Asia/Seoul`
Oceania	`Australia/Perth`, `Australia/Adelaide`, `Australia/Brisbane`, `Australia/Sydney`, `Pacific/Auckland`

Complete local list

The exact accepted list comes from the JavaScript runtime used by setup, build, the Worker, and the browser. To print the complete list supported by your local Node.js runtime:

Internationalization (i18n)

Mon, 01 Jan 0001 00:00:00 +0000

Internationalization (i18n) is the software engineering process of designing an application so it can easily adapt to different languages without requiring structural code changes. vanityURLs detects the browser language from the request and sends localized English, French, German, Italian, and Spanish web pages when they are available. The English page is sent when there is no localized page for the requested ISO language code.

Supported Languages

Code	Language
`en`	English
`fr`	French
`es`	Spanish
`it`	Italian
`de`	German

Localized Pages

The default public pages are available in the localized language directories under defaults/public/{language}/.

Link format

Mon, 01 Jan 0001 00:00:00 +0000

v8s-links.txt is the human-authored source of truth for links. Each non-empty, non-comment row is pipe-delimited:

slug|target|state|title|description|tags|owner|expires_at|notes

Field	Required	Description
`slug`	yes	Slash-delimited alias path, without leading `/`
`target`	yes	Absolute `http` or `https` URL, or a hostname normalized to `https://`
`state`	no	`permanent`, `ephemeral`, `expired`, `disabled`, `maintenance`, `deactivated`
`title`	no	Dashboard title
`description`	no	Human-readable purpose
`tags`	no	Comma-separated tags
`owner`	recommended	Accountability label
`expires_at`	no	ISO date or timestamp
`notes`	no	Internal notes

Exact links

social/x|https://x.com/vanityURLs|permanent|X / Twitter|Social profile|social,x|v8s||

The link resolves only /social/x.

Policy and blocklist

Mon, 01 Jan 0001 00:00:00 +0000

vanityURLs edits source policy as v8s-policies.json and deploys runtime policy as build/v8s-blocklist.json.

The names are intentionally described as source policy and runtime blocklist artifact throughout the docs because the current filenames are easy to confuse. A future breaking cleanup should use clearer paired names for source and generated policy files.

Built-in runtime protections are documented in Runtime security. Use Policy and blocklist when you need the operator workflow for changing instance policy.

Repository layout

Mon, 01 Jan 0001 00:00:00 +0000

A vanityURLs instance keeps product-owned files separate from instance-owned files. That is what makes npm run upgrade practical: upstream can refresh defaults/ and scripts/, while your links, branding, policy choices, and Cloudflare deployment settings stay under your control.

The public v8s.link repository follows this layout:

package.jsonnpm scripts and dependencies
package-lock.jsonlocked dependency graph
wrangler.tomlCloudflare Worker deployment settings
defaults/product baseline refreshed by upgrade
- public/default pages, assets, badges, status pages, and headers
  - _headersstatic asset cache and no-index headers
  - robots.txt
  - style.css
  - script.js
- v8s-links.txtstarter link inventory and inline schedules
- v8s-policies.jsondefault trust-and-safety policy
- v8s-blocklist-categories.jsonpolicy category labels
- v8s-language-metadata.jsonlocalized generated-page labels
- legal/default generated legal and trust copy
  - v8s-legal-content.json
- v8s-site-config.jsondefault languages, branding, and operator values
- v8s-local-config.jsondefault workstation helper settings
custom/instance-owned overrides
- public/instance branding, pages, assets, and headers
  - _headers
  - robots.txt
  - style.css
  - script.js
- v8s-links.txthuman-authored source of truth for links
- v8s-site-config.jsoninstance languages, branding, operator values, and contacts
scripts/product tooling
- workers/canonical Worker source and tests
  - worker.mjs
  - worker.test.mjs
- lnkCLI for links, schedules, and policy workflows
- build.mjsbuild defaults plus custom into deploy output
- setup.mjsnpm run setup
- upgrade.mjsnpm run upgrade
- local-install.mjslocal helper setup
- v8s.shread-only local helper
src/generated Worker entry copied from scripts/workers
- worker.mjs
build/generated deploy output
- v8s.jsonruntime redirect registry
- v8s-blocklist.jsonruntime policy artifact
- v8s-site-config.jsonruntime site configuration
- _headers
- index.html
- _stats/protected stats shell
  - index.html
- _tests/protected runtime test page
  - index.html
- en/localized public pages and assets
  - index.html
  - 404.html
  - expired.html
  - disabled.html
  - maintenance.html

Product Defaults

defaults/ is the product baseline. It contains public pages, localized status pages, redirected badges, policy pages, icons, the protected stats shell, starter links, inline starter schedules, default policy, site configuration, and local-helper defaults.

Runtime security approach

Mon, 01 Jan 0001 00:00:00 +0000

The vanityURLs runtime is deliberately small: validate the generated registry, serve static assets, read v8s.json, and return one of a small set of outcomes.

For the design rationale, read Runtime security for a small redirector. This page is the compact reference for controls to preserve.

Defensive runtime

The Worker keeps the runtime path narrow:

only public GET, HEAD, and quiet OPTIONS requests are accepted, plus POST /lookup/resolve for lookup resolution and the dedicated POST /_analytics/lookup beacon
direct access to /v8s.json, /v8s-blocklist.json, and /v8s-site-config.json returns 404
redirects allow only http: and https: targets
redirect targets with credentials, missing hostnames, control characters, or unsupported protocols fail closed
splat values are URL-encoded segment by segment before insertion
lifecycle states resolve through explicit routing rules
protected operational paths verify Cloudflare Access JWTs and fail closed when Access is not configured
scanner probes return a plain no-store 404 before short-link lookup or analytics
analytics is sent with ctx.waitUntil() so provider failure does not delay redirects

Default runtime protections include:

Security model

Mon, 01 Jan 0001 00:00:00 +0000

This page is written for security reviewers. Runtime security explains how the Worker behaves. Network protection and Access control explain what an operator configures. This page ties those views together by naming the trust boundaries and showing where each control is enforced: build time, Worker runtime, or the Cloudflare edge.

The most common review mistake is treating an edge-enforced or build-time control as missing because it is not in the Worker source. The matrix below exists to make that split explicit.

Scheduled links

Mon, 01 Jan 0001 00:00:00 +0000

Scheduled links let a stable slug point somewhere different during configured time windows. Keep the normal target on the link row in v8s-links.txt, then add indented @schedule directives below that row.

For use cases and decision guidance, read When scheduled links are useful.

Schedules currently apply to exact links. Splat links stay path-driven.

Inline form

hangout|https://discord.gg/personal|permanent|Hangout|Community hangout|community|team||
 @schedule timezone=America/Toronto
 @schedule rule=work days=mon,tue,wed,thu,fri from=09:00 to=17:00 target=https://zoom.us/j/work

The link target is the fallback target. Schedule rules only choose a temporary target during matching windows.

Upgrading an instance

Mon, 01 Jan 0001 00:00:00 +0000

Use npm run upgrade to refresh an existing vanityURLs instance. The command updates the product-owned files and leaves your instance-owned files alone.

Run it from a clean worktree:

npm run upgrade

The command fetches the configured upstream source, refreshes product files such as defaults/ and scripts/, runs the project checks, and leaves a normal Git diff for review. If package dependency definitions changed during the refresh, the upgrade runs npm install before validation so local tooling matches the updated product files.