From 36fb89f9e50be16c4fce3c429c44eb63526249e1 Mon Sep 17 00:00:00 2001
From: Michael McRae <michael@magmacomputing.com.au>
Date: Sat, 20 Jun 2026 12:00:55 +1000
Subject: [PATCH 1/6] tempo.config.ts pattern

---
 packages/tempo/CHANGELOG.md                   | 10 +++
 packages/tempo/bin/tempo.js                   | 62 +++++++++++++
 packages/tempo/doc/tempo.config.md            | 46 +++++++---
 packages/tempo/importmap.json                 | 15 ----
 packages/tempo/package.json                   |  7 +-
 packages/tempo/src/config/defineConfig.ts     |  8 ++
 packages/tempo/src/config/resolveConfig.ts    | 86 +++++++++++++++++++
 packages/tempo/src/tempo.class.ts             | 12 +++
 packages/tempo/src/tempo.index.ts             |  1 +
 packages/tempo/src/tempo.version.ts           |  2 +-
 packages/tempo/template/index.sample.html     | 63 ++++++++++++++
 .../tempo/template/tempo.config.sample.ts     | 39 +++++++++
 .../core/__fixtures__/config/tempo.config.js  |  8 ++
 packages/tempo/test/core/bootstrap.test.ts    | 34 ++++++++
 14 files changed, 363 insertions(+), 30 deletions(-)
 create mode 100755 packages/tempo/bin/tempo.js
 delete mode 100644 packages/tempo/importmap.json
 create mode 100644 packages/tempo/src/config/defineConfig.ts
 create mode 100644 packages/tempo/src/config/resolveConfig.ts
 create mode 100644 packages/tempo/template/index.sample.html
 create mode 100644 packages/tempo/template/tempo.config.sample.ts
 create mode 100644 packages/tempo/test/core/__fixtures__/config/tempo.config.js
 create mode 100644 packages/tempo/test/core/bootstrap.test.ts

diff --git a/packages/tempo/CHANGELOG.md b/packages/tempo/CHANGELOG.md
index 51177aad..dc82905f 100644
--- a/packages/tempo/CHANGELOG.md
+++ b/packages/tempo/CHANGELOG.md
@@ -6,6 +6,16 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.2.3] - 2026-06-20
+
+### Added
+- **Centralized Configuration**: Introduced `tempo.config.ts` and `tempo.config.js` discovery.
+- **Async Bootstrap**: Added `Tempo.bootstrap()` for safe, asynchronous ES Module configuration resolution without breaking the synchronous `Tempo.init()` API.
+- **CLI Scaffolding**: Added an `npx @magmacomputing/tempo scaffold:all` CLI tool to easily bootstrap `tempo.config.ts` and HTML sandboxes into projects.
+
+### Changed
+- **Zero-Dependency Resolution**: Implemented custom filesystem traversal to ensure robust config discovery without adding external dependencies (e.g., `cosmiconfig`).
+
 ## [3.2.2] - 2026-06-18
 
 ### Added
diff --git a/packages/tempo/bin/tempo.js b/packages/tempo/bin/tempo.js
new file mode 100755
index 00000000..7e911f5d
--- /dev/null
+++ b/packages/tempo/bin/tempo.js
@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// CLI Arguments
+const args = process.argv.slice(2);
+const command = args[0];
+
+// The location of the templates relative to this bin script (bin/tempo.js -> template/)
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const templateDir = path.join(__dirname, '..', 'template');
+const cwd = process.cwd();
+
+// Helper to copy a file safely
+function safelyCopy(sourceFile, targetFile, successMessage) {
+	const sourcePath = path.join(templateDir, sourceFile);
+	const targetPath = path.join(cwd, targetFile);
+
+	if (fs.existsSync(targetPath)) {
+		console.error(`\x1b[31m[Tempo Scaffold] Aborted.\x1b[0m File already exists at: ${targetPath}`);
+		console.error(`We refused to overwrite your existing file. If you want to scaffold a new one, please delete the existing file first.`);
+		process.exit(1);
+	}
+
+	if (!fs.existsSync(sourcePath)) {
+		console.error(`\x1b[31m[Tempo Scaffold] Error.\x1b[0m Could not find template file at: ${sourcePath}`);
+		process.exit(1);
+	}
+
+	try {
+		fs.copyFileSync(sourcePath, targetPath);
+		console.log(`\x1b[32m[Tempo Scaffold] Success!\x1b[0m ${successMessage}`);
+	} catch (err) {
+		console.error(`\x1b[31m[Tempo Scaffold] Failed to copy file:\x1b[0m ${err.message}`);
+		process.exit(1);
+	}
+}
+
+// Route commands
+if (command === 'scaffold:config') {
+	safelyCopy('tempo.config.sample.ts', 'tempo.config.ts', 'Created tempo.config.ts');
+} else if (command === 'scaffold:html') {
+	safelyCopy('index.sample.html', 'index.html', 'Created index.html boilerplate');
+} else if (command === 'scaffold:all') {
+	safelyCopy('tempo.config.sample.ts', 'tempo.config.ts', 'Created tempo.config.ts');
+	safelyCopy('index.sample.html', 'index.html', 'Created index.html boilerplate');
+} else {
+	console.log(`
+\x1b[36m@magmacomputing/tempo\x1b[0m CLI
+
+Available Commands:
+  scaffold:config   Copies a sample tempo.config.ts into your current directory.
+  scaffold:html     Copies a working HTML sandbox (index.html) into your current directory.
+  scaffold:all      Copies both files.
+
+Usage:
+  npx @magmacomputing/tempo <command>
+`);
+}
diff --git a/packages/tempo/doc/tempo.config.md b/packages/tempo/doc/tempo.config.md
index 0b2b9a05..d199b880 100644
--- a/packages/tempo/doc/tempo.config.md
+++ b/packages/tempo/doc/tempo.config.md
@@ -20,13 +20,17 @@ Rather than scattering `Tempo.init()` or `Tempo.extend()` calls throughout your
 
 This mirrors modern ecosystem standards (like `vite.config.ts` or `tailwind.config.js`) and ensures that plugins, timezones, and custom aliases are consistently applied before any domain logic executes.
 
+::: info
+**Target Environment**: This automatic configuration discovery pattern relies on Node.js file system capabilities and is designed for Server, Fullstack, or Bundled environments (like Vite or Webpack). If you are using Tempo via a `<script>` tag in a pure Browser environment, skip to [Explicit Initialization](#3-explicit-initialization-tempo-init) to configure Tempo synchronously!
+:::
+
 ```typescript
 // tempo.config.ts
-import { Tempo } from '@magmacomputing/tempo';
+import { defineConfig } from '@magmacomputing/tempo';
 import { CronModule } from '@magmacomputing/tempo-plugin-cron';
 import { SLAModule } from '@magmacomputing/tempo-plugin-sla';
 
-export const GlobalTempoConfig = {
+export default defineConfig({
   timeZone: 'Australia/Sydney',     // Set your baseline timezone
   license: 'eyJhbGciOiJIUzI1...',   // JWT Commercial License for Premium Plugins
   plugins: [CronModule, SLAModule], // Register enterprise plugins
@@ -36,25 +40,41 @@ export const GlobalTempoConfig = {
       'market-close': '16:00' 
     }
   }
-}
-
-// Bootstrap the global environment
-Tempo.init(GlobalTempoConfig);
+});
 ```
 
-You can then import this file at the very top of your application's entry point (e.g., `main.ts` or `index.js`) to guarantee the configuration is locked in before any other files import `Tempo`.
-
-::: tip
-**Looking to configure Internationalization?**  
-Tempo offers deep integration with native `Intl` APIs for both parsing and formatting foreign languages out-of-the-box. See [The Role of Locale](./tempo.locale.md) for a general guide, and the [Internationalized Parsing](./tempo.parse.md#internationalized-parsing-locales) and [Format Modifiers & Localization](./tempo.cookbook.md#format-modifiers--localization) guides for configuration details.
-:::
+You can then bootstrap this environment at the very top of your application's entry point (e.g., `main.ts` or `index.js`) to guarantee the configuration is locked in before any other files run:
 
 ```typescript
 // main.ts
-import './tempo.config.ts'; 
+import { Tempo } from '@magmacomputing/tempo';
+
+// Automatically discovers and loads 'tempo.config.ts'
+await Tempo.bootstrap(); 
+
 import { App } from './app.js';
 // ...
 ```
+### Benefits vs. Drawbacks
+
+Using `tempo.config.ts` is the modern standard, but it introduces specific architectural tradeoffs due to Node.js ES Module constraints.
+
+#### 🌟 Benefits
+- **TypeScript Autocomplete**: Using `defineConfig` provides instant IDE intellisense and type-safety for all configuration options.
+- **Plugin Execution**: You can import and instantiate plugins directly inside the configuration file, keeping your application logic clean.
+- **Dynamic Configuration**: Enables runtime logic (e.g., `debug: process.env.NODE_ENV !== 'production'`) that strict JSON cannot provide.
+
+#### ⚠️ Drawbacks
+- **Asynchronous Requirement**: Because `tempo.config.ts` is evaluated as an ES Module, the JavaScript engine *forces* it to be loaded asynchronously via dynamic `import()`. This means you **must** use `await Tempo.bootstrap()` instead of the synchronous `Tempo.init()`.
+
+#### 🛑 Risks
+- **Node.js Environment Only**: The `bootstrap()` automatic file discovery relies on Node.js (`fs`, `path`). If you are running strictly in a browser (e.g., via CDN without a bundler), automatic discovery will safely abort, and `bootstrap()` will simply act as a pass-through to `Tempo.init()`. In these environments, you must bundle your config or manually pass your options to `Tempo.init(options)`.
+- **Floating Promises**: You must ensure you actually `await` the bootstrap call. If you forget the `await` keyword, your application will continue booting before Tempo finishes reading your config file, leading to race conditions where early instances use default settings.
+
+::: tip
+**Looking to configure Internationalization?**  
+Tempo offers deep integration with native `Intl` APIs for both parsing and formatting foreign languages out-of-the-box. See [The Role of Locale](./tempo.locale.md) for a general guide, and the [Internationalized Parsing](./tempo.parse.md#internationalized-parsing-locales) and [Format Modifiers & Localization](./tempo.cookbook.md#format-modifiers--localization) guides for configuration details.
+:::
 
 ---
 
diff --git a/packages/tempo/importmap.json b/packages/tempo/importmap.json
deleted file mode 100644
index 8b8c7bce..00000000
--- a/packages/tempo/importmap.json
+++ /dev/null
@@ -1,15 +0,0 @@
-{
-  "_comment": "This JSON is the sanctioned browser import map for this package. Entries using './dist/...' MUST resolve relative to where this JSON is hosted (typically alongside the package's dist folder). Note that '#tempo/license' is an internal/private specifier used at runtime, which is why it differs from the public '@magmacomputing/' exports.",
-  "imports": {
-    "tslib": "https://cdn.jsdelivr.net/npm/tslib@2.8.1/tslib.es6.mjs",
-    "@js-temporal/polyfill": "https://cdn.jsdelivr.net/npm/@js-temporal/polyfill@0.5/dist/index.esm.js",
-    "@magmacomputing/tempo": "https://cdn.jsdelivr.net/npm/@magmacomputing/tempo@4/dist/tempo.bundle.esm.js",
-    "@magmacomputing/tempo/core": "./dist/core.index.js",
-    "@magmacomputing/tempo/duration": "./dist/module/module.duration.js",
-    "@magmacomputing/tempo/mutate": "./dist/module/module.mutate.js",
-    "@magmacomputing/tempo/plugin": "./dist/plugin/plugin.index.js",
-    "@magmacomputing/tempo/library": "./dist/library.index.js",
-    "@magmacomputing/tempo/enums": "./dist/support/support.enum.js",
-    "#tempo/license": "./dist/plugin/license/license.validator.js"
-  }
-}
\ No newline at end of file
diff --git a/packages/tempo/package.json b/packages/tempo/package.json
index 9f146106..5e5fd878 100644
--- a/packages/tempo/package.json
+++ b/packages/tempo/package.json
@@ -4,6 +4,9 @@
   "engines": {
     "node": ">=20.0.0"
   },
+  "bin": {
+    "tempo": "./bin/tempo.js"
+  },
   "description": "The Tempo core library",
   "author": "Magma Computing Solutions",
   "license": "MIT",
@@ -208,8 +211,10 @@
     "docs:push": "bash ./bin/push-docs.sh"
   },
   "files": [
+    "bin/",
     "dist/",
-    "img/"
+    "img/",
+    "template/"
   ],
   "dependencies": {
     "tslib": "^2.8.1"
diff --git a/packages/tempo/src/config/defineConfig.ts b/packages/tempo/src/config/defineConfig.ts
new file mode 100644
index 00000000..024b6a01
--- /dev/null
+++ b/packages/tempo/src/config/defineConfig.ts
@@ -0,0 +1,8 @@
+import type { Options } from '../tempo.type.js';
+
+/**
+ * Identity function to provide TypeScript autocomplete for Tempo configurations.
+ */
+export function defineConfig(config: Options): Options {
+	return config;
+}
diff --git a/packages/tempo/src/config/resolveConfig.ts b/packages/tempo/src/config/resolveConfig.ts
new file mode 100644
index 00000000..365ad02e
--- /dev/null
+++ b/packages/tempo/src/config/resolveConfig.ts
@@ -0,0 +1,86 @@
+import { isFunction } from '#library/assertion.library.js';
+import type { Options } from '../tempo.type.js';
+
+// Minimal declaration so TS doesn't complain in browser environments without @types/node
+declare const process: any;
+
+/**
+ * Automatically discovers and loads a tempo.config.* file by traversing upwards
+ * from the current working directory until a package.json is found.
+ */
+export async function resolveConfig(options?: { cwd?: string, configFile?: string }): Promise<Options | undefined> {
+	// Skip discovery if not in a Node/Deno/Bun environment
+	if (typeof process === 'undefined' || !isFunction(process?.cwd))
+		return undefined;
+
+	try {
+		// Use variables for dynamic imports to prevent bundlers from statically analyzing and failing
+		const modFs = 'node:fs';
+		const modUrl = 'node:url';
+		const modPath = 'node:path';
+
+		const [fs, path] = await Promise.all([
+			import(modFs),
+			import(modPath),
+		]);
+
+		let currentDir = options?.cwd || process.cwd();
+
+		const loadFile = async (configPath: string, ext: string) => {
+			if (ext === '.json') {
+				const content = fs.readFileSync(configPath, 'utf8');
+				return JSON.parse(content) as Options;
+			} else {
+				// Use pathToFileURL to safely load absolute paths on Windows
+				const { pathToFileURL } = await import(modUrl);
+				const imported = await import(pathToFileURL(configPath).href);
+				return imported.default || imported;
+			}
+		};
+
+		if (options?.configFile) {
+			const explicitPath = path.resolve(currentDir, options.configFile);
+			if (fs.existsSync(explicitPath)) {
+				try {
+					return await loadFile(explicitPath, path.extname(explicitPath));
+				} catch (err) {
+					console.warn(`[Tempo] Failed to load explicit config file at ${explicitPath}:`, err);
+					return undefined;
+				}
+			} else {
+				console.warn(`[Tempo] Explicit config file not found at ${explicitPath}`);
+				return undefined;
+			}
+		}
+
+		const rootPath = path.parse(currentDir).root;
+
+		while (currentDir !== rootPath) {
+			const pkgJson = path.join(currentDir, 'package.json');
+			const exts = ['.ts', '.js', '.mjs', '.cjs', '.json'];
+
+			for (const ext of exts) {
+				const configPath = path.join(currentDir, `tempo.config${ext}`);
+				if (fs.existsSync(configPath)) {
+					try {
+						return await loadFile(configPath, ext);
+					} catch (err) {
+						console.warn(`[Tempo] Found config file at ${configPath} but failed to load it:`, err);
+						return undefined;
+					}
+				}
+			}
+
+			if (fs.existsSync(pkgJson)) {
+				// Reached project root, stop searching
+				break;
+			}
+
+			currentDir = path.dirname(currentDir);
+		}
+	} catch (e) {
+		// Environment doesn't support node 'fs' or 'path', skip discovery
+	}
+
+	return undefined;
+}
diff --git a/packages/tempo/src/tempo.class.ts b/packages/tempo/src/tempo.class.ts
index 9e4b18a6..2c91397d 100644
--- a/packages/tempo/src/tempo.class.ts
+++ b/packages/tempo/src/tempo.class.ts
@@ -693,6 +693,18 @@ export class Tempo {
 		return resolveDisplayStatus(rt.license.status);
 	}
 
+	/** 
+	 * Automatically discovers and loads configuration from `tempo.config.*`
+	 * before initializing the engine.
+	 */
+	static async bootstrap(options?: { cwd?: string, configFile?: string }): Promise<typeof Tempo> {
+		const { resolveConfig } = await import('./config/resolveConfig.js');
+		const config = await resolveConfig(options);
+		this.init(config || {});
+		await this.ready();
+		return this;
+	}
+
 	/** Reset Tempo to its default, built-in registration state */
 	static init(options: t.Options = {}): typeof Tempo {
 		if (_lifecycle.initialising) return this;
diff --git a/packages/tempo/src/tempo.index.ts b/packages/tempo/src/tempo.index.ts
index a2fb30e5..a01318c1 100644
--- a/packages/tempo/src/tempo.index.ts
+++ b/packages/tempo/src/tempo.index.ts
@@ -22,6 +22,7 @@ Tempo.extend(core);
 
 export { parse, format } from '#tempo/module';
 export { enums };
+export { defineConfig } from './config/defineConfig.js';
 
 export * from './tempo.class.js';
 export default Tempo;
diff --git a/packages/tempo/src/tempo.version.ts b/packages/tempo/src/tempo.version.ts
index 5f794148..403d579d 100644
--- a/packages/tempo/src/tempo.version.ts
+++ b/packages/tempo/src/tempo.version.ts
@@ -5,4 +5,4 @@
  * ⚠️ This file is auto-updated by `npm run build:version` (see `bin/update-version.mjs`).
  * Do NOT edit manually — your changes will be overwritten on the next build.
  */
-export const TEMPO_VERSION = '3.2.2';
+export const TEMPO_VERSION = '3.2.3';
diff --git a/packages/tempo/template/index.sample.html b/packages/tempo/template/index.sample.html
new file mode 100644
index 00000000..bf19f78e
--- /dev/null
+++ b/packages/tempo/template/index.sample.html
@@ -0,0 +1,63 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Hello Tempo</title>
+  <!-- 
+    This is the sanctioned browser import map for Tempo.
+    Note: For production, you may want to bundle these or serve them from your own infrastructure.
+  -->
+  <script type="importmap">
+  {
+    "imports": {
+      "@js-temporal/polyfill": "https://cdn.jsdelivr.net/npm/@js-temporal/polyfill@0.5/dist/index.esm.js",
+      "@magmacomputing/tempo": "https://cdn.jsdelivr.net/npm/@magmacomputing/tempo@3/dist/tempo.bundle.esm.js",
+      "@magmacomputing/tempo/core": "./node_modules/@magmacomputing/tempo/dist/core.index.js",
+      "@magmacomputing/tempo/duration": "./node_modules/@magmacomputing/tempo/dist/module/module.duration.js",
+      "@magmacomputing/tempo/mutate": "./node_modules/@magmacomputing/tempo/dist/module/module.mutate.js",
+      "@magmacomputing/tempo/plugin": "./node_modules/@magmacomputing/tempo/dist/plugin/plugin.index.js",
+      "@magmacomputing/tempo/library": "./node_modules/@magmacomputing/tempo/dist/library.index.js",
+      "@magmacomputing/tempo/enums": "./node_modules/@magmacomputing/tempo/dist/support/support.enum.js",
+      "#tempo/license": "./node_modules/@magmacomputing/tempo/dist/plugin/license/license.validator.js"
+    }
+  }
+  </script>
+</head>
+
+<body style="font-family: sans-serif; padding: 2rem;">
+  <h1>Tempo Hello World</h1>
+  <div id="output" style="padding: 1rem; background: #f0f0f0; border-radius: 8px;">
+    Initializing Tempo...
+  </div>
+
+  <script type="module">
+    import { Tempo } from '@magmacomputing/tempo';
+
+    async function bootstrap() {
+      const output = document.getElementById('output');
+      try {
+        // Initialize the Tempo engine. 
+        // This will automatically look for 'tempo.config.ts' in modern environments, 
+        // or you can pass config options directly to Tempo.init() instead.
+        await Tempo.bootstrap();
+
+        const now = new Tempo();
+        const formatted = now.format('{wkd}, {mon} {dd}, {yyyy} at {hh}:{mi}:{ss} {mer}');
+
+        output.innerHTML = `
+          <strong>Success!</strong> Tempo is initialized.<br><br>
+          Current Local Time: <span style="color: blue;">${formatted}</span>
+        `;
+      } catch (err) {
+        output.innerHTML = `<strong style="color: red;">Error initializing Tempo:</strong> ${err.message}`;
+        console.error(err);
+      }
+    }
+
+    bootstrap();
+  </script>
+</body>
+
+</html>
\ No newline at end of file
diff --git a/packages/tempo/template/tempo.config.sample.ts b/packages/tempo/template/tempo.config.sample.ts
new file mode 100644
index 00000000..f8d48c04
--- /dev/null
+++ b/packages/tempo/template/tempo.config.sample.ts
@@ -0,0 +1,39 @@
+import { defineConfig } from '@magmacomputing/tempo';
+
+/**
+ * Tempo Configuration
+ * 
+ * This file acts as a centralized configuration for your application.
+ * When `Tempo.init()` is called without arguments, it will automatically
+ * discover and apply the settings below.
+ * 
+ * Note: These settings act as overrides to the robust defaults in `support.default.ts`.
+ */
+export default defineConfig({
+	// -------------------------------------------------------------------------
+	// -------------------------------------------------------------------------
+	// Core Engine Settings
+	// -------------------------------------------------------------------------
+	/** Defines the default time zone (e.g. 'America/New_York' or 'UTC') */
+	// timeZone: 'UTC',
+
+	/** Defines the default locale used when formatting / parsing */
+	// locale: 'en-US',
+
+	// -------------------------------------------------------------------------
+	// Layouts (Format Presets)
+	// -------------------------------------------------------------------------
+	layouts: {
+		/** Example of a custom layout accessible via now.format('iso_date') */
+		// iso_date: '{yyyy}-{mm}-{dd}',
+		// time_short: '{hh}:{mi} {mer}'
+	},
+
+	// -------------------------------------------------------------------------
+	// Plugins
+	// -------------------------------------------------------------------------
+	plugins: [
+		// Import and instantiate your plugins here
+		// TickerPlugin({ interval: 1000 })
+	]
+});
diff --git a/packages/tempo/test/core/__fixtures__/config/tempo.config.js b/packages/tempo/test/core/__fixtures__/config/tempo.config.js
new file mode 100644
index 00000000..2865613a
--- /dev/null
+++ b/packages/tempo/test/core/__fixtures__/config/tempo.config.js
@@ -0,0 +1,8 @@
+export default {
+  timeZone: 'Europe/Paris',
+  registry: {
+    periods: {
+      'custom-bootstrap-period': '13:00'
+    }
+  }
+};
diff --git a/packages/tempo/test/core/bootstrap.test.ts b/packages/tempo/test/core/bootstrap.test.ts
new file mode 100644
index 00000000..807615be
--- /dev/null
+++ b/packages/tempo/test/core/bootstrap.test.ts
@@ -0,0 +1,34 @@
+import { Tempo } from '#tempo';
+import path from 'node:path';
+
+describe('Tempo.bootstrap()', () => {
+	afterEach(() => {
+		Tempo.init();
+	});
+
+	it('should dynamically discover and load a configuration file', async () => {
+		// Resolve the fixture directory from the workspace root
+		const fixtureDir = path.resolve('./test/core/__fixtures__/config');
+
+		await Tempo.bootstrap({ cwd: fixtureDir });
+
+		expect(Tempo.config.timeZone).toBe('Europe/Paris');
+
+		const t = new Tempo('custom-bootstrap-period');
+		expect(t.isValid).toBe(true);
+		expect(t.format('{h24}:{mi}')).toBe('13:00');
+	});
+
+	it('should allow explicitly passing a configFile', async () => {
+		const fixtureDir = path.resolve('./test/core/__fixtures__/config');
+
+		// Pass the explicit file path
+		await Tempo.bootstrap({ configFile: path.join(fixtureDir, 'tempo.config.js') });
+
+		expect(Tempo.config.timeZone).toBe('Europe/Paris');
+
+		const t = new Tempo('custom-bootstrap-period');
+		expect(t.isValid).toBe(true);
+		expect(t.format('{h24}:{mi}')).toBe('13:00');
+	});
+});

From bd3d880e34dd8e6b2b860cafb5d9c21ff88d8d8f Mon Sep 17 00:00:00 2001
From: Michael McRae <michael@magmacomputing.com.au>
Date: Sat, 20 Jun 2026 12:21:46 +1000
Subject: [PATCH 2/6] PR 1st review

---
 packages/tempo/bin/tempo.js                |  8 +++++++
 packages/tempo/doc/tempo.config.md         |  5 ++--
 packages/tempo/src/config/resolveConfig.ts |  8 +++++--
 packages/tempo/template/index.sample.html  | 27 ++++++++++++++++++----
 4 files changed, 39 insertions(+), 9 deletions(-)

diff --git a/packages/tempo/bin/tempo.js b/packages/tempo/bin/tempo.js
index 7e911f5d..0bb5f30b 100755
--- a/packages/tempo/bin/tempo.js
+++ b/packages/tempo/bin/tempo.js
@@ -45,6 +45,14 @@ if (command === 'scaffold:config') {
 } else if (command === 'scaffold:html') {
 	safelyCopy('index.sample.html', 'index.html', 'Created index.html boilerplate');
 } else if (command === 'scaffold:all') {
+	const configExists = fs.existsSync(path.join(cwd, 'tempo.config.ts'));
+	const htmlExists = fs.existsSync(path.join(cwd, 'index.html'));
+	if (configExists || htmlExists) {
+		const existingFiles = [configExists ? 'tempo.config.ts' : null, htmlExists ? 'index.html' : null].filter(Boolean).join(' and ');
+		console.error(`\x1b[31m[Tempo Scaffold] Aborted.\x1b[0m File(s) already exist: ${existingFiles}`);
+		console.error(`We refused to overwrite your existing file(s). If you want to scaffold new ones, please delete the existing file(s) first.`);
+		process.exit(1);
+	}
 	safelyCopy('tempo.config.sample.ts', 'tempo.config.ts', 'Created tempo.config.ts');
 	safelyCopy('index.sample.html', 'index.html', 'Created index.html boilerplate');
 } else {
diff --git a/packages/tempo/doc/tempo.config.md b/packages/tempo/doc/tempo.config.md
index d199b880..caf74a6f 100644
--- a/packages/tempo/doc/tempo.config.md
+++ b/packages/tempo/doc/tempo.config.md
@@ -21,7 +21,7 @@ Rather than scattering `Tempo.init()` or `Tempo.extend()` calls throughout your
 This mirrors modern ecosystem standards (like `vite.config.ts` or `tailwind.config.js`) and ensures that plugins, timezones, and custom aliases are consistently applied before any domain logic executes.
 
 ::: info
-**Target Environment**: This automatic configuration discovery pattern relies on Node.js file system capabilities and is designed for Server, Fullstack, or Bundled environments (like Vite or Webpack). If you are using Tempo via a `<script>` tag in a pure Browser environment, skip to [Explicit Initialization](#3-explicit-initialization-tempo-init) to configure Tempo synchronously!
+**Target Environment**: This automatic configuration discovery pattern relies on Node.js file system capabilities and is designed for Server, Fullstack, or Bundled environments (like Vite or Webpack). If you are using Tempo via a `<script>` tag in a pure Browser environment, skip to [Explicit Initialization](#3-explicit-initialization-tempoinit) to configure Tempo synchronously!
 :::
 
 ```typescript
@@ -52,7 +52,8 @@ import { Tempo } from '@magmacomputing/tempo';
 // Automatically discovers and loads 'tempo.config.ts'
 await Tempo.bootstrap(); 
 
-import { App } from './app.js';
+// Dynamic import ensures domain logic loads ONLY AFTER configuration is complete
+const { App } = await import('./app.js');
 // ...
 ```
 ### Benefits vs. Drawbacks
diff --git a/packages/tempo/src/config/resolveConfig.ts b/packages/tempo/src/config/resolveConfig.ts
index 365ad02e..506cb422 100644
--- a/packages/tempo/src/config/resolveConfig.ts
+++ b/packages/tempo/src/config/resolveConfig.ts
@@ -7,6 +7,10 @@ declare const process: any;
 /**
  * Automatically discovers and loads a tempo.config.* file by traversing upwards
  * from the current working directory until a package.json is found.
+ * 
+ * Note: TypeScript config files require Bun, Deno, or Node.js with a TypeScript
+ * loader such as tsx, since vanilla Node.js cannot dynamically import TypeScript
+ * files without a loader.
  */
 export async function resolveConfig(options?: { cwd?: string, configFile?: string }): Promise<Options | undefined> {
 	// Skip discovery if not in a Node/Deno/Bun environment
@@ -28,7 +32,7 @@ export async function resolveConfig(options?: { cwd?: string, configFile?: strin
 
 		const loadFile = async (configPath: string, ext: string) => {
 			if (ext === '.json') {
-				const content = fs.readFileSync(configPath, 'utf8');
+				const content = await fs.promises.readFile(configPath, 'utf8');
 				return JSON.parse(content) as Options;
 			} else {
 				// Use pathToFileURL to safely load absolute paths on Windows
@@ -66,7 +70,7 @@ export async function resolveConfig(options?: { cwd?: string, configFile?: strin
 						return await loadFile(configPath, ext);
 					} catch (err) {
 						console.warn(`[Tempo] Found config file at ${configPath} but failed to load it:`, err);
-						return undefined;
+						continue;
 					}
 				}
 			}
diff --git a/packages/tempo/template/index.sample.html b/packages/tempo/template/index.sample.html
index bf19f78e..b0e50bf9 100644
--- a/packages/tempo/template/index.sample.html
+++ b/packages/tempo/template/index.sample.html
@@ -46,12 +46,29 @@ <h1>Tempo Hello World</h1>
         const now = new Tempo();
         const formatted = now.format('{wkd}, {mon} {dd}, {yyyy} at {hh}:{mi}:{ss} {mer}');
 
-        output.innerHTML = `
-          <strong>Success!</strong> Tempo is initialized.<br><br>
-          Current Local Time: <span style="color: blue;">${formatted}</span>
-        `;
+        output.textContent = '';
+        const strong = document.createElement('strong');
+        strong.textContent = 'Success!';
+        const br1 = document.createElement('br');
+        const br2 = document.createElement('br');
+        const span = document.createElement('span');
+        span.style.color = 'blue';
+        span.textContent = formatted;
+
+        output.appendChild(strong);
+        output.appendChild(document.createTextNode(' Tempo is initialized.'));
+        output.appendChild(br1);
+        output.appendChild(br2);
+        output.appendChild(document.createTextNode('\n          Current Local Time: '));
+        output.appendChild(span);
       } catch (err) {
-        output.innerHTML = `<strong style="color: red;">Error initializing Tempo:</strong> ${err.message}`;
+        output.textContent = '';
+        const strongErr = document.createElement('strong');
+        strongErr.style.color = 'red';
+        strongErr.textContent = 'Error initializing Tempo:';
+        
+        output.appendChild(strongErr);
+        output.appendChild(document.createTextNode(` ${err.message}`));
         console.error(err);
       }
     }

From 7d28da9c7ce5853d7af98ba43aa41a60f66c68df Mon Sep 17 00:00:00 2001
From: Michael McRae <michael@magmacomputing.com.au>
Date: Sat, 20 Jun 2026 16:51:46 +1000
Subject: [PATCH 3/6] package.json bin/tempo.js

---
 packages/tempo/package.json                   |  2 +-
 packages/tempo/plan/licensing_architecture.md | 81 -------------------
 2 files changed, 1 insertion(+), 82 deletions(-)
 delete mode 100644 packages/tempo/plan/licensing_architecture.md

diff --git a/packages/tempo/package.json b/packages/tempo/package.json
index 5e5fd878..127c9eba 100644
--- a/packages/tempo/package.json
+++ b/packages/tempo/package.json
@@ -211,7 +211,7 @@
     "docs:push": "bash ./bin/push-docs.sh"
   },
   "files": [
-    "bin/",
+    "bin/tempo.js",
     "dist/",
     "img/",
     "template/"
diff --git a/packages/tempo/plan/licensing_architecture.md b/packages/tempo/plan/licensing_architecture.md
deleted file mode 100644
index 490edb19..00000000
--- a/packages/tempo/plan/licensing_architecture.md
+++ /dev/null
@@ -1,81 +0,0 @@
-# Tempo Licensing Architecture & Plugin Strategy
-
-## Objective
-Implement a secure, user-friendly licensing system for Tempo plugins that enables monetization and IP protection without creating high friction for developers.
-
-## The "No-PAT" Distribution Model
-To eliminate developer friction (configuring registries/PATs), all plugins are distributed via the public npmjs registry.
-
-- **Storage**: Private source code resides in Magma Computing's GitHub organization.
-- **Distribution**: Plugins are built, minified, and obfuscated before being published as public packages under the `@magmacomputing` scope (e.g., `@magmacomputing/plugin-term`).
-- **Access**: Anyone can `npm install`, but functionality is gated by the "Tempo Activation Key" (JWT).
-- **Free Tier**: The "Astrological Sign" plugin serves as a free reference implementation for users to test the activation and support model.
-
-## Activation & Validation
-
-### 1. The Tempo Activation Key (JWT)
-The key is a JSON Web Token issued to the customer. It supports three tiers of usage:
-
-| Claim | Standard/Trial | Enterprise/Distribution |
-| :--- | :--- | :--- |
-| `aud` (Audience) | Array of domains (e.g. `["localhost", "site.com"]`) | `"*"` (Wildcard - works on any domain) |
-| `exp` (Expiry) | Unix timestamp (e.g. 1 year from issue) | `0` (Perpetual - never expires) |
-| `jti` | Unique ID for revocation | Unique ID for revocation |
-
-### 2. Cascade of License Discovery
-Plugins will look for the activation key in the following order:
-1. **Explicit**: `Tempo.init({ license: '...' })`
-2. **Discovery**: `globalThis.__TEMPO_DISCOVERY__.license`
-3. **Environment**: `process.env.TEMPO_LICENSE` (Server-side)
-4. **Configuration**: `.temporc` or `tempo.config.json` (CWD)
-5. **Storage**: `localStorage.getItem('tempo_license')` (Client-side)
-
-### 3. Verification Logic
-- **Domain Locking**: The plugin verifies `window.location.hostname` against the `aud` claim (unless `aud` is `*`).
-- **Grace Period**: If a key is expired, the plugin enters a 7-day "Grace Period," allowing full functionality while emitting a `console.warn`.
-- **Revocation**:
-    - Plugins fetch a **Signed Revocation List** (JWS) from Magma's servers every **7 days**.
-    - The fetch is shared across all Tempo plugins to minimize overhead.
-    - If offline, the plugin "Fails Open" and relies on the JWT's internal expiry.
-    - The list is self-cleaning; keys are removed once they naturally expire.
-
-### 4. The License "Wallet" (Discovery & Persistence)
-To prevent "Token Fatigue" and the need to re-supply keys, Tempo and its plugins treat the environment as a persistent wallet.
-
-- **One Key, Many Scopes**: A single JWT can contain multiple plugin identifiers in its `scope` claim (e.g., `scope: ["term", "ticker"]`).
-- **Global Discovery (Browser)**: Developers can define `window.__TEMPO_DISCOVERY__ = { license: '...' }` at the very top of their HTML. Any Tempo instance or plugin will automatically "hydrate" from this global wallet.
-- **Internal Stashing**: Once a license is discovered or provided via `init()`, Tempo core caches it in its internal static state. This ensures that a plugin imported in a different module (or a secondary Tempo instance) can still find the active license without being explicitly passed a key.
-- **Cross-Session Persistence (Opt-in & Unsafe)**: By default, Tempo avoids `localStorage` due to XSS token-theft risks. Persistence is **opt-in** via the `enableCrossSessionPersistence` flag.
-    - **Recommended**: Use memory or `sessionStorage` for sensitive keys.
-    - **Mitigation Checklist**:
-        - Implement strict Content Security Policy (CSP).
-        - Use HttpOnly cookies for token delivery where possible.
-        - Ensure rigorous input sanitization.
-        - Use short TTLs and rotate/revoke tokens frequently.
-
-### 5. Revocation Infrastructure (The Control Tower)
-To maintain security without manual intervention on the customer side:
-
-- **Host**: `api.magmacomputing.com.au`
-- **Endpoint**: `/tempo/v1/revoked.jws` (Versioned for future-proofing).
-- **Format**: The list is a Signed JWS. Plugins verify it using an embedded Public Key.
-- **Management**: 
-    - A local `registry/` folder in the private `tempo-plugin` repo tracks the revocation state.
-    - CLI tools (`npm run license:revoke`) handle the signing and deployment of the updated JWS to the production host.
-- **Security**: The **Private Key** for signing is stored as a GH Secret and never committed. The **Public Key** is baked into the obfuscated plugin source.
-- **Fail-Safe**: If the endpoint is unreachable, plugins "Fail Open" and rely on the internal JWT expiry to ensure no service disruption for legitimate users.
-
-## Implementation Roadmap
-
-### Phase 1: Support Infrastructure
-- [ ] Add `license` to `Internal.State` and `BaseOptions` in Tempo Core.
-- [ ] Implement the Discovery Cascade and Shared Revocation Service.
-- [ ] Ensure `Logify` and internal state dumps redact the `state.license` branch.
-
-### Phase 2: Reference Plugin (Astro)
-- [ ] Create the `@magmacomputing/plugin-astro` workspace.
-- [ ] Implement JWS signature verification and JWT decoding.
-- [ ] Set up the obfuscated build pipeline for public npmjs distribution.
-
-### Phase 3: Commercial Plugins
-- [ ] Roll out `term`, `ticker`, and other premium extensions using the proven Astro model.

From 213cccc425d9b510e3dcd3130b32f8fbf89737ee Mon Sep 17 00:00:00 2001
From: Michael McRae <michael@magmacomputing.com.au>
Date: Sun, 21 Jun 2026 13:07:17 +1000
Subject: [PATCH 4/6] Localized Modifiers

---
 packages/tempo/CHANGELOG.md                   | 14 ++-
 packages/tempo/bench/modifiers.ts             | 38 ++++++++
 .../bench/results/modifiers_post_refactor.txt |  0
 ...modifiers_pre_refactor_20260621_075533.txt | 27 ++++++
 packages/tempo/doc/tempo.config.md            |  4 +-
 packages/tempo/doc/tempo.cookbook.md          | 20 +++++
 packages/tempo/doc/tempo.parse.md             |  7 +-
 packages/tempo/package.json                   |  2 +-
 packages/tempo/plan/ticker-reactive.md        | 55 ------------
 packages/tempo/src/engine/engine.lexer.ts     | 42 +++++----
 packages/tempo/src/engine/engine.pattern.ts   | 28 +++++-
 packages/tempo/src/engine/engine.term.ts      | 38 +++++++-
 packages/tempo/src/module/module.parse.ts     |  9 +-
 packages/tempo/src/support/support.default.ts | 46 ++++++----
 packages/tempo/src/support/support.enum.ts    |  2 +-
 packages/tempo/src/support/support.init.ts    | 34 +++++++-
 packages/tempo/src/tempo.class.ts             | 46 +++++++---
 packages/tempo/src/tempo.type.ts              |  7 +-
 packages/tempo/src/tempo.version.ts           |  2 +-
 packages/tempo/template/locales.sample.ts     | 79 +++++++++++++++++
 packages/tempo/test/engine/modifiers.test.ts  | 87 +++++++++++++++++++
 21 files changed, 461 insertions(+), 126 deletions(-)
 create mode 100644 packages/tempo/bench/modifiers.ts
 create mode 100644 packages/tempo/bench/results/modifiers_post_refactor.txt
 create mode 100644 packages/tempo/bench/results/modifiers_pre_refactor_20260621_075533.txt
 delete mode 100644 packages/tempo/plan/ticker-reactive.md
 create mode 100644 packages/tempo/template/locales.sample.ts
 create mode 100644 packages/tempo/test/engine/modifiers.test.ts

diff --git a/packages/tempo/CHANGELOG.md b/packages/tempo/CHANGELOG.md
index dc82905f..8f06353a 100644
--- a/packages/tempo/CHANGELOG.md
+++ b/packages/tempo/CHANGELOG.md
@@ -6,9 +6,21 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [3.2.3] - 2026-06-20
+## [3.3.0] - 2026-06-21
 
 ### Added
+- **Localization Modifier Registry**: Modifiers (e.g., "next", "last", "this") can now be localized via the `registry.modifiers` configuration. This allows defining custom words for temporal shifts (e.g., `'>': ['prochain']`) which seamlessly integrate with standard parsing and `#` shorthand syntaxes.
+
+### Changed
+- **Unified Registry Architecture**: Moved the top-level `modifiers` configuration key under the `registry` namespace (`registry: { modifiers }`) to maintain architectural consistency with formats and locales. Deep-merging ensures English default keywords remain active alongside custom localized additions.
+- **Lexer Token Cleanups**: Stripped hardcoded English keywords out of all internal Match regular expressions (`Match.modifier`, `Match.shorthand`, `Match.slick`), standardizing the engine on the symbolic modifiers (`>`, `<`, `=`, `+`, `-`).
+
+### Fixed
+- **Pre-filter Guard Numeric Safety**: Refined the guard-bypass logic to trigger *only* when the input string actually contains a registered modifier keyword, restoring proper strictness and fixing numeric-safety validation gaps for nanosecond epoch inputs.
+- **Lazy Evaluation Delegation**: Fixed a regression in format lazy-loading where built-in formats (like `{date}` or `{time}`) were temporarily eclipsed by empty registry instances.
+- **Trailing Affix Collisions**: Added explicit safety checks and warnings when a date unit is passed both a leading modifier and a trailing affix (e.g., "next May ago").
+
+## [3.2.3] - 2026-06-20
 - **Centralized Configuration**: Introduced `tempo.config.ts` and `tempo.config.js` discovery.
 - **Async Bootstrap**: Added `Tempo.bootstrap()` for safe, asynchronous ES Module configuration resolution without breaking the synchronous `Tempo.init()` API.
 - **CLI Scaffolding**: Added an `npx @magmacomputing/tempo scaffold:all` CLI tool to easily bootstrap `tempo.config.ts` and HTML sandboxes into projects.
diff --git a/packages/tempo/bench/modifiers.ts b/packages/tempo/bench/modifiers.ts
new file mode 100644
index 00000000..090f7a39
--- /dev/null
+++ b/packages/tempo/bench/modifiers.ts
@@ -0,0 +1,38 @@
+import '@js-temporal/polyfill';
+import { Tempo } from '../src/tempo.class.js';
+
+const ITERATIONS = 100_000;
+
+function runBenchmark(name: string, expression: string) {
+	const start = performance.now();
+	for (let i = 0; i < ITERATIONS; i++) {
+		new Tempo(expression);
+	}
+	const end = performance.now();
+	const duration = end - start;
+	const opsPerSec = Math.round((ITERATIONS / duration) * 1000);
+
+	console.log(`[${name}]`);
+	console.log(`  Expression : "${expression}"`);
+	console.log(`  Duration   : ${duration.toFixed(2)} ms`);
+	console.log(`  Speed      : ${opsPerSec.toLocaleString()} ops/sec`);
+	console.log('');
+}
+
+console.log('=============================================');
+console.log(`Tempo Modifier Benchmark (${ITERATIONS.toLocaleString()} iterations)`);
+console.log('=============================================\n');
+
+// 1. Standard Prefix Modifier (Weekday)
+runBenchmark('Prefix Weekday', 'next Friday');
+
+// 2. Relative Offset (Ago/Hence)
+runBenchmark('Relative Offset', '3 days ago');
+
+// 3. Complex Expression
+runBenchmark('Complex Expression', 'next Friday at 5:00pm');
+
+// 4. Baseline (No modifier)
+runBenchmark('Baseline Date', '2025-01-01');
+
+console.log('Benchmark complete.\n');
diff --git a/packages/tempo/bench/results/modifiers_post_refactor.txt b/packages/tempo/bench/results/modifiers_post_refactor.txt
new file mode 100644
index 00000000..e69de29b
diff --git a/packages/tempo/bench/results/modifiers_pre_refactor_20260621_075533.txt b/packages/tempo/bench/results/modifiers_pre_refactor_20260621_075533.txt
new file mode 100644
index 00000000..0528b8af
--- /dev/null
+++ b/packages/tempo/bench/results/modifiers_pre_refactor_20260621_075533.txt
@@ -0,0 +1,27 @@
+Criteria: Pre Tempo Modifiers refactor
+=============================================
+Tempo Modifier Benchmark (100,000 iterations)
+=============================================
+
+[Prefix Weekday]
+  Expression : "next Friday"
+  Duration   : 1300.42 ms
+  Speed      : 76,898 ops/sec
+
+[Relative Offset]
+  Expression : "3 days ago"
+  Duration   : 1265.60 ms
+  Speed      : 79,014 ops/sec
+
+[Complex Expression]
+  Expression : "next Friday at 5:00pm"
+  Duration   : 1580.71 ms
+  Speed      : 63,263 ops/sec
+
+[Baseline Date]
+  Expression : "2025-01-01"
+  Duration   : 1657.52 ms
+  Speed      : 60,331 ops/sec
+
+Benchmark complete.
+
diff --git a/packages/tempo/doc/tempo.config.md b/packages/tempo/doc/tempo.config.md
index caf74a6f..16841a8b 100644
--- a/packages/tempo/doc/tempo.config.md
+++ b/packages/tempo/doc/tempo.config.md
@@ -157,7 +157,7 @@ Tempo looks for the following structure:
 | `plugins` | `Plugin \| Plugin[]` | Modular plugin(s) (including `TermPlugin`s) to be extended onto Tempo automatically. |
 | `timeZones` | `Record<string, string>` | Custom timezone aliases to be merged. |
 | `numbers` | `Record<string, number>` | Custom number-word aliases merged into the NUMBER registry. |
-| `registry` | `{ formats?, locales?, events?, periods?, snippets?, layouts?, ignores? }` | Custom configuration for internal dictionary registries. |
+| `registry` | `{ formats?, locales?, events?, periods?, snippets?, layouts?, ignores?, modifiers? }` | Custom configuration for internal dictionary registries. |
 
 ---
 
@@ -188,7 +188,7 @@ Tempo.init({
 | `timeStamp`| `'ss' \| 'ms' \| 'us' \| 'ns'` | `'ms'` | Precision for numeric inputs and the `.ts` property. |
 | `sphere` | `'north' \| 'south'`| Auto-inferred | Hemisphere for seasonal plugins. |
 | `intl` | `IntlOptions` | `undefined` | Internationalization configuration grouping `relativeTimeFormat`, `numberFormat`, and `durationFormat`. |
-| `registry` | `{ formats?, locales?, events?, periods?, snippets?, layouts?, ignores? }` | Built-in registries | Custom data augmentation registries (e.g., format aliases, parsing logic, localization). |
+| `registry` | `{ formats?, locales?, events?, periods?, snippets?, layouts?, ignores?, modifiers? }` | Built-in registries | Custom data augmentation registries (e.g., format aliases, parsing logic, localization). |
 | `plugins` | `Plugin \| Plugin[]` | `[]` | Plugins/modules to extend during initialization. Unlike `registry` options, these values are not merged into internal state via `extendState`; `Tempo.init()` applies each plugin with `Tempo.extend(p)`, so plugin authors should treat them as instance/class augmentations rather than internal-state merges. |
 | `store` | `string` | `'$Tempo'` | Persistent storage key used by `readStore`/`writeStore`. |
 | `discovery` | `string \| symbol` | `'$Tempo'` symbol key | Discovery slot used to resolve global discovery config. |
diff --git a/packages/tempo/doc/tempo.cookbook.md b/packages/tempo/doc/tempo.cookbook.md
index 7d959e90..42af60fe 100644
--- a/packages/tempo/doc/tempo.cookbook.md
+++ b/packages/tempo/doc/tempo.cookbook.md
@@ -75,6 +75,26 @@ new Tempo('2 weeks ago');
 new Tempo('tomorrow afternoon');
 ```
 
+### Localized Parsing Modifiers
+Tempo allows you to localize term modifiers (like `next`, `last`, `this`) by defining them in the `registry.modifiers` configuration. This lets you seamlessly mix localized terms into your relative string parsing and even use them in the `#` shorthand navigation engine!
+
+```typescript
+Tempo.init({
+  locale: 'fr-FR',                // Natively translates months & weekdays
+  registry: {
+    modifiers: {
+      '>': ['prochain', 'suivant'],
+      '<': ['dernier', 'passé'],
+      '=': ['ce', 'cette']
+    }
+  }
+});
+
+new Tempo('next Friday');         // English always works natively
+new Tempo('vendredi prochain');   // Pure French localized string!
+new Tempo('#qtr.dernier');        // Localized shorthand navigation
+```
+
 ### Parsing Unix Timestamps
 Tempo handles both milliseconds (Number) and nanoseconds (BigInt).
 ```typescript
diff --git a/packages/tempo/doc/tempo.parse.md b/packages/tempo/doc/tempo.parse.md
index 81294ed5..4efdce40 100644
--- a/packages/tempo/doc/tempo.parse.md
+++ b/packages/tempo/doc/tempo.parse.md
@@ -149,11 +149,10 @@ It also automatically **normalizes and strips accents** from these generated rul
 
 #### ⚠️ Current Limitations (What is NOT Available)
 While `Intl` provides a robust foundation for month and weekday translations, there are limits to auto-localization:
-*   **English Affixes**: Grammatical connector words like "ago", "next", "last", "in", and "from now" are heavily English-biased syntax rules. `Intl` does not provide translations for these parsing connectors. When parsing non-English languages, a relative string like `2 days ago` or `next Friday` will only parse correctly if the English connector keywords (`ago`, `next`) are used, unless Custom Aliases are used to bridge the gap.
 *   **Duration Units**: Words representing duration units ("days", "weeks", "months", "hours") inside natural language strings are currently English-only.
 *   **Grammar Structure**: The parser expects sequences matching standard English formats (e.g., `[value] [unit] [affix]`). Highly inflected languages or completely different phrase structures might fail to parse.
 
-To bridge these gaps, you can register **Custom Aliases** (see below) to map foreign syntax to specific relative offsets manually!
+To bridge these gaps, you can register **Custom Aliases** (see below) or define custom localized keywords in `registry.modifiers`.
 
 ### Custom Aliases (Events & Periods)
 You can teach the parser new words or entire foreign phrases to bridge translation gaps:
@@ -164,7 +163,7 @@ Tempo.init({
   registry: {
     events: {
       // Map a full foreign phrase directly to an English-equivalent relative string
-      'vendredi prochain': 'next Friday',
+      'le lendemain': 'tomorrow',
       // Or standard static events
       'launch': '2026-12-01',
       'party': () => 'next Friday 8pm'
@@ -172,7 +171,7 @@ Tempo.init({
   }
 });
 
-const t1 = new Tempo('vendredi prochain'); // Parses accurately to next Friday
+const t1 = new Tempo('le lendemain'); // Parses accurately to tomorrow
 const t2 = new Tempo('party');
 ```
 
diff --git a/packages/tempo/package.json b/packages/tempo/package.json
index 127c9eba..57eb7993 100644
--- a/packages/tempo/package.json
+++ b/packages/tempo/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@magmacomputing/tempo",
-  "version": "3.2.3",
+  "version": "3.3.0",
   "engines": {
     "node": ">=20.0.0"
   },
diff --git a/packages/tempo/plan/ticker-reactive.md b/packages/tempo/plan/ticker-reactive.md
deleted file mode 100644
index ab8a097d..00000000
--- a/packages/tempo/plan/ticker-reactive.md
+++ /dev/null
@@ -1,55 +0,0 @@
-# Plan: Reactive Ticker Enhancements
-
-## Overview
-This document outlines the requirements and design for making `Tempo.ticker` more dynamic and reactive to environment changes.
-
-## 1. Dynamic Updates
-### Requirements
-- Ability to update a running ticker's configuration without stopping and restarting.
-- Support for updating the following properties:
-    - **Interval**: Change the pulse frequency (e.g., from 1s to 1m).
-    - **Limit**: Extend or shorten the number of remaining ticks.
-    - **Until**: Adjust the stopping boundary.
-    - **TimeZone**: Shift the ticker's time perspective.
-    - **Seed**: Reset the "current" time of the ticker.
-
-### Proposed API
-```typescript
-const clock = Tempo.ticker({ seconds: 1 });
-
-// Later...
-clock.update({ 
-    seconds: 60, // slow down
-    timeZone: 'Europe/Paris' // shift perspective
-});
-```
-
-## 2. Environment Reactivity (The "Analog Clock" Scenario)
-### Problem
-An analog clock using `Tempo.ticker` on a mobile device or laptop may become "wrong" if the user travels across TimeZone boundaries. Currently, the ticker is pinned to the TimeZone detected at creation.
-
-### Discussion
-- **Detection**: How does the ticker know the TimeZone changed?
-    - Option A: Periodic check (e.g., every 60 seconds) of `Intl.DateTimeFormat().resolvedOptions().timeZone`.
-    - Option B: Check on every pulse (low overhead for `Intl` calls).
-- **Behavior**: If a change is detected:
-    - Should it automatically adopt the new TZ?
-    - Should it emit an event (e.g., `ticker.on('timezonechange', ...)`?
-- **"Discrepancy" Logic**:
-    - The user suggested checking for a "wide-enough" discrepancy in mutations. 
-    - *Antigravity's Note*: Since the `epoch` is continuous, a TZ shift only affects the "wall clock" representation. A simpler check is just comparing the current system TZ name against the ticker's internal TZ name.
-
-### Use Case: Analog Clock
-For a clock, "Self-Adjustment" is a premium feature. If `autoTimeZone: true` is set, the ticker would:
-1. Verify the system timezone on each pulse.
-2. If it differs from the ticker's current timezone, it performs an internal `.set({ timeZone: newTz })`.
-3. The next `Tempo` instance emitted to the UI will have the correct hour hand position.
-
-## 3. Implementation Challenges
-- **Scheduling**: If the `interval` changes, the pending `setTimeout` must be cleared and recalculated.
-- **Immutability**: `Tempo` instances are immutable. The `TickerInstance` (manager) must handle the swapping of its internal `#current` reference safely.
-- **Performance**: Frequent `Intl` checks are generally fast, but we should ensure they don't impact 16ms (60fps) pulse loops if someone is using the ticker for animations.
-
----
-*Date: 2026-04-19*
-*Status: Discussion / Requirement Gathering*
diff --git a/packages/tempo/src/engine/engine.lexer.ts b/packages/tempo/src/engine/engine.lexer.ts
index 7e19a802..c99c38c0 100644
--- a/packages/tempo/src/engine/engine.lexer.ts
+++ b/packages/tempo/src/engine/engine.lexer.ts
@@ -1,6 +1,7 @@
 import '#library/temporal.polyfill.js';
 import { isString, isEmpty, isUndefined, isDefined, isTemporal, isInstant } from '#library/assertion.library.js';
 import { ownKeys, ownEntries } from '#library/primitive.library.js';
+
 import { pad, singular } from '#library/string.library.js';
 import { Match, enums, isTempo, logError, logWarn, logDebug } from '#tempo/support';
 import * as t from '../tempo.type.js';
@@ -74,30 +75,33 @@ export function prefix(str: any): any {
 	return str;
 }
 
-/** resolve a relative modifier (+, -, next, ago, etc) */
-export function parseModifier({ mod, adjust, offset, period }: Lexer.GroupModifier) {
+/** resolve a relative modifier (+, -, <, >, =, etc) */
+export function parseModifier({ mod, adjust, offset, period }: Lexer.GroupModifier, config: any = {}) {
 	adjust = Math.abs(adjust);
+	if (mod && config?.registry?.modifiers) {
+		const norm = mod.toLowerCase().trim().normalize('NFD').replace(/[\u0300-\u036f]/g, "");
+		for (const [sym, words] of Object.entries(config.registry.modifiers)) {
+			if ((words as string[]).map(w => w.toLowerCase().trim().normalize('NFD').replace(/[\u0300-\u036f]/g, "")).includes(norm)) {
+				mod = sym as t.Modifier;
+				break;
+			}
+		}
+	}
+
 	switch (mod) {
-		case void 0:
+		case undefined:
 		case '=':
-		case 'this':
 			return 0
 		case '+':
-		case 'next':
 			return adjust;
 		case '-':
-		case 'prev':
-		case 'last':
 			return -adjust;
 		case '<':
-		case 'ago':
 			return (period <= offset) ? -adjust : -(adjust - 1);
 		case '<=':
 		case '-=':
 			return (period < offset) ? -adjust : -(adjust - 1);
 		case '>':
-		case 'hence':
-		case 'from now':
 			return (period >= offset) ? adjust : (adjust - 1);
 		case '>=':
 		case '+=':
@@ -144,7 +148,7 @@ export function parseWeekday(groups: t.Groups, dateTime: Temporal.ZonedDateTime,
 	}
 
 	const days = offset - dateTime.dayOfWeek
-		+ (parseModifier({ mod: mod ?? sfx ?? afx, adjust, offset, period: dateTime.dayOfWeek }) * dateTime.daysInWeek);
+		+ (parseModifier({ mod: mod ?? sfx ?? afx, adjust, offset, period: dateTime.dayOfWeek }, config) * dateTime.daysInWeek);
 
 	delete groups["wkd"];
 	delete groups["mod"];
@@ -160,16 +164,16 @@ export function parseWeekday(groups: t.Groups, dateTime: Temporal.ZonedDateTime,
 export function parseDate(groups: t.Groups, dateTime: Temporal.ZonedDateTime, config: any, pivot: number = 75): Temporal.ZonedDateTime {
 
 	const { mod, nbr = '1', afx, unt } = groups as Lexer.GroupDate;
-	// Normalize yy, mm, dd: treat empty string as missing
-	const yy = (typeof groups.yy === 'string' && groups.yy.trim() === '') ? undefined : groups.yy;
-	const mm = (typeof groups.mm === 'string' && groups.mm.trim() === '') ? undefined : groups.mm;
-	const dd = (typeof groups.dd === 'string' && groups.dd.trim() === '') ? undefined : groups.dd;
+	// Normalize yy, mm, dd: treat empty captures as missing (regex groups yield '' for optional unmatched groups)
+	const yy = groups.yy || undefined;
+	const mm = groups.mm || undefined;
+	const dd = groups.dd || undefined;
 
 	if (isEmpty(yy) && isEmpty(mm) && isEmpty(dd) && isUndefined(unt))
 		return dateTime;
 
 	if (!isEmpty(mod) && !isEmpty(afx)) {
-		logWarn(`Cannot provide both a modifier '${mod}' and suffix '${afx}'`, config);
+		logWarn(`A date unit cannot have both a leading modifier ('${mod}') and a trailing affix ('${afx}') — use one or the other`, config);
 		return dateTime;
 	}
 
@@ -191,7 +195,8 @@ export function parseDate(groups: t.Groups, dateTime: Temporal.ZonedDateTime, co
 
 	if (unt) {
 		const { nbr: adjust = 1 } = num({ nbr });
-		const direction = (mod === '<' || mod === '-' || afx === 'ago') ? -1 : 1;
+		const dir = parseModifier({ mod: mod ?? afx, adjust: 1, offset: 0, period: 0 }, config);
+		const direction = dir < 0 ? -1 : 1;
 		const plural = `${singular(unt)}s`;
 		dateTime = dateTime.add({ [plural]: adjust * direction } as any);
 
@@ -214,7 +219,8 @@ export function parseDate(groups: t.Groups, dateTime: Temporal.ZonedDateTime, co
 	const period = Number(pad(dateTime.month) + '.' + pad(dateTime.day + 1));
 	const tz = (dateTime as any).timeZoneId ?? (dateTime as any).timeZone;
 
-	year += parseModifier({ mod: mod ?? afx, adjust, offset, period });
+	const pmRes = parseModifier({ mod: mod ?? afx, adjust, offset, period }, config);
+	year += pmRes;
 	Object.assign(groups, { yy: year, mm: month, dd: day });
 
 	delete groups["mod"];
diff --git a/packages/tempo/src/engine/engine.pattern.ts b/packages/tempo/src/engine/engine.pattern.ts
index 2721935d..81964bb9 100644
--- a/packages/tempo/src/engine/engine.pattern.ts
+++ b/packages/tempo/src/engine/engine.pattern.ts
@@ -120,8 +120,32 @@ export class PatternCompiler {
 			const nbr = new RegExp(`(?<nbr>[0-9]+|${keys.sort((a, b) => b.length - a.length).join('|')})`);
 
 			snippet[Token.nbr] = nbr;
-			snippet[Token.mod] = new RegExp(`((?<mod>${Match.modifier.source})?${nbr.source}? *)`);
-			snippet[Token.afx] = new RegExp(`((s)? (?<afx>${Match.affix.source}))?${snippet[Token.sep]?.source || ''}?`);
+			
+			let modPattern = Match.modifier.source;
+			let afxPattern = Match.modifier.source;
+			if (state.config.registry?.modifiers) {
+				const symbols = ['+', '-', '<', '<=', '>', '>=', '='];
+				const words = new Set<string>();
+				symbols.forEach(sym => {
+					const mapped = state.config.registry!.modifiers![sym];
+					if (mapped) (Array.isArray(mapped) ? mapped : [mapped]).forEach(w => words.add(w));
+				});
+				if (words.size > 0) {
+					const escapedWords = Array.from(words).map(w => w.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+					escapedWords.sort((a, b) => b.length - a.length);
+					const wordPattern = escapedWords.join('|');
+					modPattern = `[\\+\\-\\<\\>][\\=]?|${wordPattern}`;
+					afxPattern = `[\\+\\-\\<\\>][\\=]?|${wordPattern}`;
+					
+					const op = `[\\+\\-\\<\\>]=?`;
+					const terms = `(?:#[\\w]+|[\\w]+)`;
+					const units = `(?:[\\w]*)`;
+					snippet[Token.slk as any] = new RegExp(`(?:${terms}\\.(?:${op}|${wordPattern})?(?:[0-9]+)?${units})`, 'i');
+				}
+			}
+
+			snippet[Token.mod] = new RegExp(`((?<mod>${modPattern})? *)`, 'i');
+			snippet[Token.afx] = new RegExp(`((s)? (?<afx>${afxPattern}))?${snippet[Token.sep]?.source || ''}?`, 'i');
 		}
 
 		// 2. build ignore pattern
diff --git a/packages/tempo/src/engine/engine.term.ts b/packages/tempo/src/engine/engine.term.ts
index 4e8d27e9..4e44898c 100644
--- a/packages/tempo/src/engine/engine.term.ts
+++ b/packages/tempo/src/engine/engine.term.ts
@@ -53,12 +53,42 @@ export function resolveTermMutation(Tempo: TempoTermType, instance: Tempo, mutat
 
 	const slickStr = (rangePart ? unit : (isString(offset) ? offset : undefined));
 	if (slickStr) {
-		const slick = slickStr.match(Match.slick) || (isString(offset) ? offset.match(Match.slickValue) : null);
+		let matchSlick = Match.slick;
+		let matchSlickValue = Match.slickValue;
+		if (state.config.registry?.modifiers) {
+			const symbols = ['+', '-', '<', '<=', '>', '>=', '='];
+			const words = new Set<string>();
+			symbols.forEach(sym => {
+				const mapped = state.config.registry!.modifiers![sym];
+				if (mapped) (Array.isArray(mapped) ? mapped : [mapped]).forEach(w => words.add(w));
+			});
+			if (words.size > 0) {
+				const escapedWords = Array.from(words).map(w => w.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+				escapedWords.sort((a, b) => b.length - a.length);
+				const wordPattern = escapedWords.join('|');
+				// Preserve the original term group (including # prefix) from Match.slick; only extend mod alternation
+				matchSlick = new RegExp(`^(?<sh_term>#[\\w]+|[\\w]+)\\.(?<sh_mod>[\\+\\-\\<\\>]=?|${wordPattern})?(?<sh_nbr>[0-9]+)?(?<sh_unit>[\\w]*)$`);
+				matchSlickValue = new RegExp(`^(?<sh_mod>[\\+\\-\\<\\>]=?|${wordPattern})?(?<sh_nbr>[0-9]+)?(?<sh_unit>[\\w]*)$`);
+			}
+		}
+
+		const slick = slickStr.match(matchSlick) || (isString(offset) ? offset.match(matchSlickValue) : null);
 		const { groups } = (slick || {}) as any;
 		if (groups) {
 			const hasMod = isDefined(groups.sh_mod);
 			const hasNbr = isNumeric(groups.sh_nbr);
 			mod = hasMod ? groups.sh_mod : undefined;
+
+			if (mod && state.config.registry?.modifiers) {
+				const norm = mod.toLowerCase().trim();
+				for (const [sym, words] of Object.entries(state.config.registry.modifiers)) {
+					if ((words as string[]).includes(norm)) {
+						mod = sym;
+						break;
+					}
+				}
+			}
+
 			nbr = hasNbr ? Number(groups.sh_nbr) : 1;
 			rKey = (groups.sh_unit && groups.sh_unit.length > 0) ? groups.sh_unit : (hasMod ? undefined : rKey);
 			numericOnly = hasNbr && !hasMod;
@@ -312,7 +342,7 @@ export function resolveTermMutation(Tempo: TempoTermType, instance: Tempo, mutat
 			// Treat explicit modifiers and + / - as shifters. Numeric repeat counts
 			// without an explicit modifier (e.g. `2q2`) are handled as inclusive
 			// searches and should not be treated as shifters.
-			const isShifter = (mod === '>' || mod === '<' || mod === 'next' || mod === 'prev' || mod === 'last' || mod === '+' || mod === '-');
+			const isShifter = (mod === '>' || mod === '<' || mod === '+' || mod === '-');
 
 			const compare = (r: any) => {
 				const start = toZdt(r.start).epochNanoseconds as bigint;
@@ -328,7 +358,7 @@ export function resolveTermMutation(Tempo: TempoTermType, instance: Tempo, mutat
 					const res = parseModifier({
 						mod: mod as any, adjust: 1, offset: Number(cursor / 1000000n),
 						period: Number((mod === '-') ? end / 1000000n : start / 1000000n)
-					});
+					}, state.config);
 					match = res !== 0;
 				} else {																						// Absolute Search or Inclusive mod
 					const offset = Number(cursor / 1000000n);
@@ -338,7 +368,7 @@ export function resolveTermMutation(Tempo: TempoTermType, instance: Tempo, mutat
 						const res = parseModifier({
 							mod: mod as any, adjust: 1, offset,
 							period: Number(start / 1000000n)
-						});
+						}, state.config);
 						match = res === 0;
 					}
 				}
diff --git a/packages/tempo/src/module/module.parse.ts b/packages/tempo/src/module/module.parse.ts
index 2156ed7a..3a4149f0 100644
--- a/packages/tempo/src/module/module.parse.ts
+++ b/packages/tempo/src/module/module.parse.ts
@@ -224,8 +224,14 @@ const _ParseEngine = {
 			let guard = (TempoClass as any)?.[sym.$guard]?.test(trim) ?? true;
 
 			// 🛡️ Bypass the strict global guard if the current instance is using localized parsing
-			if (!guard && !isEmpty(state.parse.monthMap)) {
+			if (!guard && (!isEmpty(state.parse.monthMap) || !isEmpty(state.parse.weekdayMap)))
 				guard = true;
+
+			// Also bypass if the input itself matches a registered modifier word (e.g. localized 'prochain', 'siguiente')
+			if (!guard && state.config.registry?.modifiers) {
+				const modWords = (Object.values(state.config.registry.modifiers) as string[][]).flat();
+				if (modWords.some(w => trim.toLowerCase().includes(w.toLowerCase())))
+					guard = true;
 			}
 
 			if (!guard) {
@@ -342,7 +348,6 @@ const _ParseEngine = {
 		for (const [symKey, pat] of orderedPatterns) {
 			const groups = _ParseEngine.parseMatch(state, pat, trim);
 
-
 			if (isEmpty(groups))
 				continue;
 
diff --git a/packages/tempo/src/support/support.default.ts b/packages/tempo/src/support/support.default.ts
index cc9fa17b..04657d97 100644
--- a/packages/tempo/src/support/support.default.ts
+++ b/packages/tempo/src/support/support.default.ts
@@ -22,19 +22,18 @@ export const Match = proxify({
 	/** structural */																					named: /^g?dt$|^g?tm$/,
 	/** two digit year */																			twoDigit: /^[0-9]{2}$/,
 	/** date (ISO 8601) */																		date: /^(?:[+-][0-9]{6}|[0-9]{4})-?(?:0[1-9]|1[0-2])-?(?:0[1-9]|[12][0-9]|3[01])$/,
-	/** time (HH:mm[:ss]) */																	time: /^(?:[01][0-9]|2[0-3]):[0-5][0-9](?::[0-5][0-9])?|24:00(?::00)?$/,
-	/** clock (HH:mm[:ss][.ffffff]) */												clock: /^(?:[01]?\d|2[0-3]):[0-5]\d(?::[0-5]\d)?(?:\.\d{1,9})?|24:00(?::00)?(?:\.0{1,9})?$/,
+	/** time (hh:mi[:ss]) */																	time: /^(?:[01][0-9]|2[0-3]):[0-5][0-9](?::[0-5][0-9])?|24:00(?::00)?$/,
+	/** clock (hh:mi[:ss][.ffffff]) */												clock: /^(?:[01]?\d|2[0-3]):[0-5]\d(?::[0-5]\d)?(?:\.\d{1,9})?|24:00(?::00)?(?:\.0{1,9})?$/,
 	/** separator characters (/ - . , T) */										separator: /[T\/\-\.\s,]/,
-	/** modifier characters (+-<>=) */												modifier: /[\+\-\<\>][\=]?|this|next|prev|last/,
-	/** offset post keywords (ago|hence) */										affix: /ago|hence|from now/,
+	/** modifier characters (+-<>=) */												modifier: /[\+\-\<\>][\=]?/,
 	/** strip out these characters from a string */						strips: /\(|\)/g,
 	/** whitespace characters */															spaces: /\s+/g,
 	/** Z character */																				zed: /^Z$/,
 	/** base guard characters (digits and common symbols) */	guard: /[\d\s\-\.\:T\/Z\+\-\(\)\,\=\#\<\>]/i,
 	/** bracketed content (timezone/calendar) */							bracket: /\[[^\]]+\]/i,
-	/** slick shorthand-shifter (e.g. #qtr.>2q2) */						shorthand: /(?:(?:#[\w]+|[\w]+)\.(?:[\+\-\<\>]=?|next|prev|this|last)?(?:[0-9]+)?(?:[\w]*))/,
-	/** anchored version for shifter resolution */						slick: /^(?<sh_term>#[\w]+|[\w]+)\.(?<sh_mod>[\+\-\<\>]=?|next|prev|this|last)?(?<sh_nbr>[0-9]+)?(?<sh_unit>[\w]*)$/,
-	/** extracted value-only version of a slick shifter */		slickValue: /^(?<sh_mod>[\+\-\<\>]=?|next|prev|this|last)?(?<sh_nbr>[0-9]+)?(?<sh_unit>[\w]*)$/,
+	/** slick shorthand-shifter (e.g. #qtr.>2q2) */						shorthand: /(?:(?:#[\w]+|[\w]+)\.(?:[\+\-\<\>]=?)?(?:[0-9]+)?(?:[\w]*))/,
+	/** anchored version for shifter resolution */						slick: /^(?<sh_term>#[\w]+|[\w]+)\.(?<sh_mod>[\+\-\<\>]=?)?(?<sh_nbr>[0-9]+)?(?<sh_unit>[\w]*)$/,
+	/** extracted value-only version of a slick shifter */		slickValue: /^(?<sh_mod>[\+\-\<\>]=?)?(?<sh_nbr>[0-9]+)?(?<sh_unit>[\w]*)$/,
 	/** escape special regex characters in a string */				escape: (str: string) => String(str).replace(/[.*+?^${}()|[\]\\]/g, '\\$&'),
 	/** escape only dangerous quantifiers and anchors to prevent backtracking/injection while allowing basic regex */
 	safeAlias: (str: string) => String(str).replace(/[*+{}!^$\\]/g, '\\$&'),
@@ -63,18 +62,18 @@ export const Snippet = looseIndex<symbol, RegExp>()({
 	[Token.mi]: /(\:(?<mi>[0-5][0-9]))/,											// minute-number 00-59
 	[Token.ss]: /(\:(?<ss>[0-5][0-9]))/,											// seconds-number 00-59
 	[Token.ff]: /(\.(?<ff>[0-9]{1,9}))/,											// fractional-seconds up-to 9-digits
-	[Token.ord]: /(?:\s?(?:st|nd|rd|th))/,										// optional ordinal suffix
+	[Token.ord]: /(?:\s?(?:st|nd|rd|th|e|er|re|ème|eme))?/i,	// optional ordinal suffix
 	[Token.mer]: /(\s*(?<mer>am|pm))/,												// meridiem suffix (am,pm)
 	[Token.sfx]: /((?:{sep}+|T)({tm}){tzd}?)/,								// time-pattern suffix 'T {tm} Z'; NOTE: {tm} resolves via Layout fallback in compileRegExp (cross-registry dependency: Snippet → Layout)
 	[Token.wkd]: /(?<wkd>Mon(?:day)?|Tue(?:sday)?|Wed(?:nesday)?|Thu(?:rsday)?|Fri(?:day)?|Sat(?:urday)?|Sun(?:day)?)/,	// day-name (abbrev or full)
 	[Token.tzd]: /(?<tzd>Z|(?:\+(?:(?:0[0-9]|1[0-3]):?[0-5][0-9]|14:?00)|-(?:(?:0[0-9]|1[0-1]):?[0-5][0-9]|12:?00)))/,	// time-zone offset +14:00 to -12:00; colon optional throughout (including boundary values UTC+14 and UTC-12)
 	[Token.nbr]: new RegExp(`(?<nbr>[0-9]+|${Object.keys(NUMBER).map(w => Match.escape(w)).join('|')})`),	// modifier count; number-word keys are regex-escaped at construction time (setPatterns() also re-escapes, but defence-in-depth)
-	[Token.afx]: new RegExp(`((s)? (?<afx>${Match.affix.source}))?{sep}?`),	// affix optional plural 's' and (ago|hence)
-	[Token.mod]: new RegExp(`((?<mod>${Match.modifier.source})?{nbr}? *)`),	// modifier (+,-,<,<=,>,>=) plus optional count; CAUTION: all sub-components are optional so this snippet always matches the empty string — standard layouts all use {mod}? to reflect this
+	[Token.afx]: new RegExp(`((s)? (?<afx>${Match.modifier.source}))?{sep}?`),	// affix optional plural 's' and (ago|hence)
+	[Token.mod]: new RegExp(`((?<mod>${Match.modifier.source})? *)`),
 	[Token.sep]: new RegExp(`(?:${Match.separator.source})`),	// date-input separator character "/\\-., " (non-capture group)
 	[Token.unt]: /(?<unt>year|month|week|day|hour|minute|second|millisecond)(?:s)?/,	// useful for '2 days ago' etc
 	[Token.brk]: new RegExp(`(\\[(?<brk>${bracket_content.source})\\](?:\\[(?<cal>${bracket_content.source})\\])?)?`),	// timezone/calendar brackets [...]
-	[Token.slk]: new RegExp(`${Match.shorthand.source}`),			// shorthand shifter
+	[Token.slk]: new RegExp(Match.shorthand.source),					// shorthand shifter
 })
 /** @internal Tempo Snippet type */
 export type Snippet = typeof Snippet
@@ -85,8 +84,8 @@ export type Snippet = typeof Snippet
  */
 /** @internal Layout components for date resolution */
 export const datePattern = {
-	dmy: '({dd}{sep}?{mm}({sep}?{yy})?|{mod}?({evt})|(?<slk>{slk})|{wkd})',
-	mdy: '({mm}{sep}?{dd}({sep}?{yy})?|{mod}?({evt})|(?<slk>{slk})|{wkd})'
+	dmy: '{mod}?(?:{dd}{sep}?{mm}({sep}?{yy})?|{evt}|(?<slk>{slk})|{wkd}){afx}?',
+	mdy: '{mod}?(?:{mm}{sep}?{dd}({sep}?{yy})?|{evt}|(?<slk>{slk})|{wkd}){afx}?'
 }
 
 /** @internal Tempo Layout registry */
@@ -95,14 +94,14 @@ export const Layout = looseIndex<symbol, string>()({
 	[Token.dmy6]: '(?<dd>0[1-9]|[12][0-9]|3[01])(?<mm>0[1-9]|1[0-2])(?<yy>[0-9]{2})',// compact date (ddmmyy)
 	[Token.mdy6]: '(?<mm>0[1-9]|1[0-2])(?<dd>0[1-9]|[12][0-9]|3[01])(?<yy>[0-9]{2})',// compact date (mmddyy)
 	[Token.ymd6]: '(?<yy>[0-9]{2})(?<mm>0[1-9]|1[0-2])(?<dd>0[1-9]|[12][0-9]|3[01])',// compact date (yymmdd)
-	[Token.wkd]: '{mod}?{wkd}{afx}?{sfx}?',										// weekday-only layout; MUST precede {dt} (which also matches bare weekday names via its {wkd} alternative)
+	[Token.wkd]: '{mod}?{nbr}?{wkd}{afx}?{sfx}?',							// weekday-only layout; MUST precede {dt} (which also matches bare weekday names via its {wkd} alternative)
 	[Token.dt]: datePattern.dmy,															// calendar, event, slick or weekday
 	[Token.tm]: '({hh}{mi}?{ss}?{ff}?{mer}?|{per})',					// clock or period
 	[Token.dtm]: '({dt})(?:(?:{sep}+|T)({tm}))?{tzd}?{brk}?',	// calendar/event and clock/period
 	[Token.tmd]: '({tm})(?:(?:{sep}+|T)({dt}))?{tzd}?{brk}?',	// clock/period and calendar/event
-	[Token.dmy]: '({wkd}{sep}+)?{dd}{sep}?{mm}({sep}?{yy})?{sfx}?{brk}?',// day-month(-year)
-	[Token.mdy]: '({wkd}{sep}+)?{mm}{sep}?{dd}({sep}?{yy})?{sfx}?{brk}?',// month-day(-year)
-	[Token.ymd]: '({wkd}{sep}+)?{yy}{sep}?{mm}({sep}?{dd})?{sfx}?{brk}?',// year-month(-day)
+	[Token.dmy]: '{mod}?({wkd}{sep}+)?{dd}{sep}?{mm}({sep}?{yy})?{afx}?{sfx}?{brk}?',// day-month(-year)
+	[Token.mdy]: '{mod}?({wkd}{sep}+)?{mm}{sep}?{dd}({sep}?{yy})?{afx}?{sfx}?{brk}?',// month-day(-year)
+	[Token.ymd]: '{mod}?({wkd}{sep}+)?{yy}{sep}?{mm}({sep}?{dd})?{afx}?{sfx}?{brk}?',// year-month(-day)
 	[Token.off]: '{mod}?{dd}{afx}?',													// day of month, with optional offset
 	[Token.rel]: '{nbr}{sep}?{unt}{sep}?{afx}',								// relative duration (e.g. 2 days ago)
 })
@@ -213,6 +212,19 @@ export const Default = secure({
 	/** hemisphere for term.qtr or term.szn */								sphere: undefined,
 	/** regional date-parsing configuration */								monthDay: MONTH_DAY,
 	/** internationalization configuration */									intl: IntlDefault,
+	/** global data augmentation registries */								registry: {
+		formats: {},
+		locales: {},
+		modifiers: {
+			'+': ['next', 'hence', 'from now'],
+			'-': ['ago', 'last', 'prev'],
+			'=': ['this'],
+			'<': [],
+			'>': [],
+			'<=': [],
+			'>=': [],
+		}
+	},
 	/** parse planner configuration (layoutOrder, etc.) */		planner: {
 		layoutOrder: [
 			Token.hms, Token.dmy6, Token.mdy6, Token.ymd6, Token.wkd,
diff --git a/packages/tempo/src/support/support.enum.ts b/packages/tempo/src/support/support.enum.ts
index 9617d10e..76eedfc1 100644
--- a/packages/tempo/src/support/support.enum.ts
+++ b/packages/tempo/src/support/support.enum.ts
@@ -243,7 +243,7 @@ export type ZONED_DATE_TIME = ValueOf<typeof ZONED_DATE_TIME>
 export type ZonedDateTime = KeyOf<typeof ZONED_DATE_TIME>
 
 /** allowed keys for Tempo configuration options */
-const configKeys = ['config', 'parse', 'value', 'intl', 'store', 'discovery', 'debug', 'catch', 'timeZone', 'calendar', 'locale', 'sphere', 'timeStamp', 'formats', 'plugins', 'locales'] as const;
+const configKeys = ['config', 'parse', 'value', 'intl', 'store', 'discovery', 'debug', 'catch', 'timeZone', 'calendar', 'locale', 'sphere', 'timeStamp', 'registry', 'plugins'] as const;
 export const CONFIG = enumify(configKeys, false);
 export type Config = KeyOf<typeof CONFIG>
 
diff --git a/packages/tempo/src/support/support.init.ts b/packages/tempo/src/support/support.init.ts
index 6d61331f..e7d6cb9d 100644
--- a/packages/tempo/src/support/support.init.ts
+++ b/packages/tempo/src/support/support.init.ts
@@ -93,6 +93,14 @@ export function init(options: t.Options = {}, isGlobal = true, baseState?: t.Int
 	const configDefaults = Object.fromEntries(Object.entries(Default).filter(([key]) => enums.CONFIG.has(key)));
 	if (isGlobal) {
 		markConfig(Object.assign(state.config, configDefaults));
+		// Unfreeze the registry sub-object so that extendState can write into it at runtime.
+		// Default.registry is frozen (via secure()), so we need a mutable shallow clone.
+		if (state.config.registry) {
+			state.config.registry = {
+				...state.config.registry,
+				modifiers: { ...(state.config.registry.modifiers ?? {}) }
+			}
+		}
 		const { timeZone, calendar } = getDateTimeFormat();
 		setProperties(state.config, {
 			calendar,
@@ -119,6 +127,13 @@ export function init(options: t.Options = {}, isGlobal = true, baseState?: t.Int
 		Object.defineProperty(state.config, 'get', { value: function (key: string) { return this[key] }, enumerable: false, writable: true, configurable: true });
 	} else {
 		markConfig(Object.assign(state.config, configDefaults));
+		// Unfreeze the registry sub-object so that extendState can write into it at runtime.
+		if (state.config.registry) {
+			state.config.registry = {
+				...state.config.registry,
+				modifiers: { ...(state.config.registry.modifiers ?? {}) }
+			}
+		}
 		setProperties(state.config, {
 			calendar,
 			timeZone,
@@ -220,6 +235,23 @@ export function extendState(state: t.Internal.State, options: t.Options): boolea
 						if ((state.config.registry.locales as any)?.extend) state.config.registry.locales = (state.config.registry.locales as any).extend(arg.value.locales);
 						else setProperty(state.config.registry, 'locales', arg.value.locales);
 					}
+					if (arg.value.modifiers) {
+						// Deep-merge user modifiers with existing defaults so English keywords remain active
+						const existing = state.config.registry.modifiers ?? {};
+						const merged: Record<string, string[]> = {};
+
+						// normalize existing defaults into arrays
+						for (const [op, words] of Object.entries(existing))
+							merged[op] = [...asArray<string>(words as any)];
+
+						// merge incoming user modifiers
+						for (const [op, words] of Object.entries(arg.value.modifiers)) {
+							const current = merged[op] ?? [];
+							merged[op] = [...new Set([...current, ...asArray<string>(words as any)])];
+						}
+
+						setProperty(state.config.registry, 'modifiers', merged);
+					}
 
 					const parseMap: Record<string, 'snippet' | 'layout' | 'event' | 'period' | 'ignore'> = {
 						snippets: 'snippet',
@@ -227,7 +259,7 @@ export function extendState(state: t.Internal.State, options: t.Options): boolea
 						events: 'event',
 						periods: 'period',
 						ignores: 'ignore'
-					};
+					}
 
 					ownEntries(arg.value).forEach(([k, v]) => {
 						if (isString(k) && k in parseMap) {
diff --git a/packages/tempo/src/tempo.class.ts b/packages/tempo/src/tempo.class.ts
index 2c91397d..94ef4018 100644
--- a/packages/tempo/src/tempo.class.ts
+++ b/packages/tempo/src/tempo.class.ts
@@ -297,7 +297,7 @@ export class Tempo {
 	private static _locale = (locale?: string | string[]) => {
 		const global = Context.global;
 		let language: string | undefined;
-		
+
 		const primaryLocale = Array.isArray(locale) ? locale[0] : locale;
 
 		if (primaryLocale) language = canonicalLocale(primaryLocale);
@@ -324,7 +324,11 @@ export class Tempo {
 
 		// Apply options using extendState
 		const patternsDirty = extendState(shape, mergedOptions);
-		if (patternsDirty) setPatterns(shape);
+		if (patternsDirty) {
+			setPatterns(shape);
+			if (shape.config.scope === 'local')
+				this[$buildGuard](shape);
+		}
 
 		// Side-effects
 		const newSphere = Tempo._setSphere(shape, mergedOptions);
@@ -433,7 +437,8 @@ export class Tempo {
 		return res;
 	}
 
-	static [$buildGuard]() {
+	static [$buildGuard](targetState?: Internal.State) {
+		const state = targetState ?? this[$Internal]();
 		const wordsList = [
 			...Object.keys(enums.NUMBER),
 			...Object.keys(enums.WEEKDAY),
@@ -443,17 +448,24 @@ export class Tempo {
 			...Object.keys(enums.DURATION),
 			...Object.keys(enums.DURATIONS),
 			...Object.keys(enums.TIMEZONE),
-			...(this[$Internal]().aliasEngine?.getAliases(undefined, true).map((a: any) => a.name) ?? []),
-			...ownKeys(this[$Internal]().parse.ignore),
-			...ownKeys(this[$Internal]().parse.snippet),
-			...ownKeys(this[$Internal]().parse.layout),
+			...(state.aliasEngine?.getAliases(undefined, true).map((a: any) => a.name) ?? []),
+			...ownKeys(state.parse.ignore),
+			...ownKeys(state.parse.snippet),
+			...ownKeys(state.parse.layout),
 			...[Token.slk],
 			...Tempo._terms.map(t => t.key),
 			...Tempo._terms.map(t => t.scope),
-			...Guard
+			...Guard,
+			...(state.config.registry?.modifiers ? Object.values(state.config.registry.modifiers).flat() : [])
 		];
 
-		(this[$Internal]() as any)[$guard] = createMasterGuard(wordsList);
+		const guard = createMasterGuard(wordsList);
+
+		if (targetState) {
+			targetState.parse.guard = guard as any;
+		} else {
+			(this[$Internal]() as any)[$guard] = guard;
+		}
 
 		if (this[$Internal]() === _global) {
 			setPatterns(this[$Internal]());
@@ -976,7 +988,11 @@ export class Tempo {
 
 	/** @deprecated Use Tempo.registry.formats instead */
 	static get formats() {
-		return Tempo.config.registry.formats;
+		// Extend built-in enums.FORMAT with any user-registered formats, preserving Enum methods (.keys(), .values(), etc.)
+		const userFormats = Tempo.config.registry?.formats;
+		return (userFormats && Object.keys(userFormats).length > 0)
+			? enums.FORMAT.extend(userFormats, false)
+			: enums.FORMAT;
 	}
 
 	/** static Tempo properties getter */
@@ -1168,13 +1184,13 @@ export class Tempo {
 
 		const { mode } = this.#local.parse;
 		const input = String(this.#tempo ?? '');
+		const guard = this.#local.parse.guard || (this.constructor as typeof Tempo)[$guard];
 
 		// 🏛️ Initialization Strategy ('auto' | 'strict' | 'defer')
 		if (mode === Tempo.MODE.Defer) this.#local.parse.lazy = true;
 		else if (mode === Tempo.MODE.Strict) this.#local.parse.lazy = false;
-		else if (isString(this.#tempo) && !isEmpty(input) && (this.constructor as typeof Tempo)[$guard].test(trimAll(input))) {
+		else if (isString(this.#tempo) && !isEmpty(input) && guard.test(trimAll(input)))
 			this.#local.parse.lazy = true;												// auto-switch to lazy-mode for valid strings
-		}
 
 		this.#fmt = this.#setDelegator('fmt');									// initialize the format-delegator
 		this.#term = this.#setDelegator('term');								// initialize the term-delegator
@@ -1306,7 +1322,8 @@ export class Tempo {
 			// discovery phase
 			if (host === 'fmt') {
 				if (!ensureModule(this, 'FormatModule')) return undefined;
-				if (isDefined(this.#local.config.registry.formats[key]))
+				const allFormats = Object.assign({}, enums.FORMAT, this.#local.config.registry?.formats);
+				if (isDefined(allFormats[key]))
 					return this.#setLazy(target, key, () => this.format(key as t.Format))?.();
 			} else {
 				if (!ensureModule(this, 'TermsModule')) return undefined;
@@ -1352,7 +1369,8 @@ export class Tempo {
 	#discover(host: 'term' | 'fmt', target: any) {
 		if (!_lifecycle.ready) return;
 		if (host === 'fmt') {
-			ownKeys(this.#local.config.registry.formats).forEach(key => {
+			const allFormats = Object.assign({}, enums.FORMAT, this.#local.config.registry?.formats);
+			ownKeys(allFormats).forEach(key => {
 				if (isString(key)) this.#setLazy(target, key, () => this.format(key as t.Format));
 			});
 		} else {
diff --git a/packages/tempo/src/tempo.type.ts b/packages/tempo/src/tempo.type.ts
index 8f78cef2..496d4d5a 100644
--- a/packages/tempo/src/tempo.type.ts
+++ b/packages/tempo/src/tempo.type.ts
@@ -240,6 +240,7 @@ export namespace Internal {
 		/** custom data augmentation registries */							registry?: { 
 			formats?: Property<any>;
 			locales?: Record<string, Record<string, string | Function>>;
+			modifiers?: Record<string, string | string[]>;
 			snippets?: Snippet | RegistryOption<Pattern>;
 			layouts?: Layout | RegistryOption<Pattern>;
 			events?: Event | RegistryOption<Logic>;
@@ -324,8 +325,8 @@ export namespace Internal {
 	/** Instance configuration derived from supply, storage, and discovery. */
 	export interface Config extends Required<Omit<OptionsKeep, "formats" | "locales" | "registry" | "license" | "localize">> {
 		/** license key for premium features */									license?: string;
-		/** configuration (global | local) */										scope: 'global' | 'local';
-		/** custom data augmentation registries */							registry: { formats: FormatRegistry, locales: Record<string, Record<string, string | Function>> };
+		/** scope for configuration mutations */								scope: 'global' | 'local';
+		/** custom data augmentation registries */							registry: { formats: FormatRegistry, locales: Record<string, Record<string, string | Function>>, modifiers?: Record<string, string | string[]> };
 		/** index-signature */																	readonly [key: string]: any;
 	}
 
@@ -340,7 +341,7 @@ export namespace Internal {
 		/** internationalization configuration (relativeTime, etc.) */intl?: IntlOptions;
 		/** @deprecated Provide configuration inside `registry: { formats: ... }` */formats?: Property<any>;
 		/** @deprecated Provide configuration inside `registry: { locales: ... }` */locales?: Record<string, Record<string, string | Function>>;
-		/** custom data augmentation registries */							registry?: { formats?: Property<any>, locales?: Record<string, Record<string, string | Function>> };
+		/** custom data augmentation registries */							registry?: { formats?: Property<any>, locales?: Record<string, Record<string, string | Function>>, modifiers?: Record<string, string | string[]> };
 		/** noise words to ignore during parsing via Tempo.ignore() */ignore?: Ignore;
 		/** plugins to be automatically extended via Tempo.extend() */plugins?: (TempoPlugin | TermPlugin) | (TempoPlugin | TermPlugin)[];
 	}
diff --git a/packages/tempo/src/tempo.version.ts b/packages/tempo/src/tempo.version.ts
index 403d579d..06a8e5e8 100644
--- a/packages/tempo/src/tempo.version.ts
+++ b/packages/tempo/src/tempo.version.ts
@@ -5,4 +5,4 @@
  * ⚠️ This file is auto-updated by `npm run build:version` (see `bin/update-version.mjs`).
  * Do NOT edit manually — your changes will be overwritten on the next build.
  */
-export const TEMPO_VERSION = '3.2.3';
+export const TEMPO_VERSION = '3.3.0';
diff --git a/packages/tempo/template/locales.sample.ts b/packages/tempo/template/locales.sample.ts
new file mode 100644
index 00000000..f40ce80c
--- /dev/null
+++ b/packages/tempo/template/locales.sample.ts
@@ -0,0 +1,79 @@
+/**
+ * Tempo Locale Configuration Cookbook
+ * 
+ * This file provides sample localized dictionaries and format patterns for Tempo.
+ * You can mix these configurations into your `tempo.config.ts` to add multi-language support.
+ * 
+ * Localized Modifiers Map:
+ *  - '>' maps to "next", "future"
+ *  - '<' maps to "last", "previous", "past"
+ *  - '=' maps to "this", "current"
+ */
+
+
+
+// ==========================================
+// French (fr)
+// ==========================================
+export const fr_FR = {
+	locale: 'fr-FR',
+	// Localized TimeZone resolution
+	timeZones: {
+		'cet': 'Europe/Paris',
+		'cest': 'Europe/Paris'
+	},
+	// Localized custom formats & modifiers
+	registry: {
+		formats: {
+			'frenchDate': '{dd} {mmm} {yyyy}',
+			'frenchTime': '{hh}h{mi}',
+		},
+		modifiers: {
+			'>': ['prochain', 'prochaine', 'dans', 'suivant', 'suivante'],
+			'<': ['dernier', 'dernière', 'il y a', 'passé', 'passée'],
+			'=': ['ce', 'cette']
+		}
+	}
+}
+
+// ==========================================
+// Spanish (es)
+// ==========================================
+export const es_ES = {
+	locale: 'es-ES',
+	// Localized TimeZone resolution
+	timeZones: {
+		'cet': 'Europe/Madrid',
+		'cest': 'Europe/Madrid',
+		'wet': 'Atlantic/Canary'
+	},
+	// Localized custom formats & modifiers
+	registry: {
+		formats: {
+			'spanishDate': '{dd} {mmm} {yyyy}',
+			'spanishTime': '{hh}:{mi}',
+		},
+		modifiers: {
+			'>': ['próximo', 'próxima', 'en', 'siguiente'],
+			'<': ['pasado', 'pasada', 'hace', 'último', 'última'],
+			'=': ['este', 'esta']
+		}
+	}
+}
+
+// ==========================================
+// Usage Example
+// ==========================================
+/*
+import { defineConfig } from '@magmacomputing/tempo';
+import { deepMerge } from '@magmacomputing/tempo/library';
+import { fr_FR, es_ES } from './locales.sample.js';
+
+// To merge multiple locales:
+// const combinedLocales = deepMerge(fr_FR, es_ES);
+
+export default defineConfig({
+	// ... your other config
+	...fr_FR
+});
+*/
diff --git a/packages/tempo/test/engine/modifiers.test.ts b/packages/tempo/test/engine/modifiers.test.ts
new file mode 100644
index 00000000..4d86c55c
--- /dev/null
+++ b/packages/tempo/test/engine/modifiers.test.ts
@@ -0,0 +1,87 @@
+import { Tempo, defineConfig } from '#tempo';
+
+describe('Localized Modifiers', () => {
+
+	test('should parse localized prefix and suffix modifiers for weekdays', () => {
+		const config = defineConfig({
+			registry: {
+				modifiers: {
+					'>': ['prochain'],
+					'<': ['dernier']
+				}
+			}
+		});
+
+		const now = new Tempo('2026-06-20T12:00:00+10:00', config); // Saturday
+
+		const prochainFriday = new Tempo('prochain friday', { ...config, anchor: now });
+		expect(prochainFriday.dow).toBe(5);
+		expect(prochainFriday.toPlainDate().toString() > now.toPlainDate().toString()).toBe(true);
+
+		const fridayDernier = new Tempo('friday dernier', { ...config, anchor: now });
+		expect(fridayDernier.dow).toBe(5);
+		expect(fridayDernier.toPlainDate().toString() < now.toPlainDate().toString()).toBe(true);
+	});
+
+	test('should parse localized prefix and suffix modifiers for explicit dates', () => {
+		const config = defineConfig({
+			registry: {
+				modifiers: {
+					'>': ['prochain'],
+					'<': ['dernier']
+				}
+			}
+		});
+
+		const now = new Tempo('2026-06-20T12:00:00+10:00', config);
+		
+		const nextMay = new Tempo('1 May prochain', { ...config, anchor: now });
+		if (nextMay.yy !== 2027) throw new Error("nextMay.yy is " + nextMay.yy + " month: " + nextMay.mm + " day: " + nextMay.day);
+		expect(nextMay.mm).toBe(5);
+		expect(nextMay.day).toBe(1);
+		expect(nextMay.yy).toBeGreaterThan(2026);
+
+		const pastMay = new Tempo('1 May dernier', { ...config, anchor: now });
+		expect(pastMay.mm).toBe(5);
+		expect(pastMay.day).toBe(1);
+		expect(pastMay.yy).toBe(2026);
+
+		const pastAugust = new Tempo('1 August dernier', { ...config, anchor: now });
+		expect(pastAugust.mm).toBe(8);
+		expect(pastAugust.day).toBe(1);
+		expect(pastAugust.yy).toBe(2025);
+	});
+
+	test('should respect partial match fallback sorting (longest-match first)', () => {
+		const config = defineConfig({
+			registry: {
+				modifiers: {
+					'>': ['dans', 'dans la', 'en']
+				}
+			}
+		});
+
+		const now = new Tempo('2026-06-20T12:00:00+10:00', config);
+
+		const futureDate = new Tempo('1 May dans la', { ...config, anchor: now });
+		expect(futureDate.mm).toBe(5);
+		expect(futureDate.day).toBe(1);
+		expect(futureDate.yy).toBeGreaterThan(2026);
+	});
+
+	test('should map shorthand localized terms correctly', () => {
+		const config = defineConfig({
+			registry: {
+				modifiers: {
+					'>': ['prochain']
+				}
+			}
+		});
+
+		const now = new Tempo('2026-06-20T12:00:00+10:00', config);
+
+		// shorthand shift using localized term
+		const nextQtr = new Tempo('#qtr.prochain', { ...config, anchor: now });
+		expect(nextQtr.mm).toBeGreaterThan(6);
+	});
+});

From 158c125ba0c81c2ca1978f73ba66df970e48413b Mon Sep 17 00:00:00 2001
From: Michael McRae <michael@magmacomputing.com.au>
Date: Sun, 21 Jun 2026 13:13:18 +1000
Subject: [PATCH 5/6] post benchmark tests

---
 packages/tempo/bench/bench.v3.3.0.ts          | 164 ++++++++++++++++++
 .../tempo/bench/benchmark-results-v3.3.0.json |  63 +++++++
 2 files changed, 227 insertions(+)
 create mode 100644 packages/tempo/bench/bench.v3.3.0.ts
 create mode 100644 packages/tempo/bench/benchmark-results-v3.3.0.json

diff --git a/packages/tempo/bench/bench.v3.3.0.ts b/packages/tempo/bench/bench.v3.3.0.ts
new file mode 100644
index 00000000..b3618538
--- /dev/null
+++ b/packages/tempo/bench/bench.v3.3.0.ts
@@ -0,0 +1,164 @@
+/**
+ * Post-refactor (v3.3.0) representative benchmark
+ *
+ * Compares three configurations:
+ *   A. Baseline: stock Tempo, same corpus as pre-refactor
+ *   B. Localized modifiers: registry.modifiers + locale:'fr-FR' active
+ *   C. English relative strings through the new modifier path
+ */
+import '../bin/temporal-polyfill.js';
+import { Tempo } from '../src/tempo.index.js';
+import { BenchmarkModule } from '../src/module/module.benchmark.js';
+import { performance } from 'node:perf_hooks';
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// ── Corpus ──────────────────────────────────────────────────────────────────
+
+/** Same 20-entry corpus used for the pre-refactor benchmark */
+const baseCorpus: string[] = [
+	'04012026',
+	'310559',
+	'590531',
+	'09:30',
+	'monday',
+	'2 days ago',
+	'+6',
+	'1234567890123',
+	'2026-04-25',
+	'2026/04/25 10:30',
+	'11:45pm',
+	'tomorrow',
+	'2026-04-25T10:30:00Z',
+	'2026-04-25T10:30:00+05:30',
+	'next Friday at 5pm',
+	'last Monday',
+	'in 3 weeks',
+	'yesterday',
+	'noon',
+	'midnight',
+];
+
+/** New v3.3.0 corpus: French localized modifiers through registry.modifiers */
+const frCorpus: string[] = [
+	'vendredi prochain',		// localized 'next Friday'
+	'lundi dernier',			// localized 'last Monday'
+	'mercredi prochain',		// localized 'next Wednesday'
+	'3 jours',				// plain French numeric
+	'vendredi',				// plain French weekday
+	'jeudi dernier',			// localized 'last Thursday'
+	'mardi suivant',			// alias: suivant => >
+	'dimanche prochain',		// localized 'next Sunday'
+];
+
+// ── Benchmark helpers ───────────────────────────────────────────────────────
+
+function timedRun(label: string, data: string[], iterations: number, tempoOptions: any) {
+	// warm-up
+	for (const d of data) new Tempo(d, { catch: true, ...tempoOptions });
+
+	let success = 0, failure = 0;
+	const startHeap = process.memoryUsage().heapUsed;
+	const start = performance.now();
+
+	for (let i = 0; i < iterations; i++) {
+		for (const d of data) {
+			const t = new Tempo(d, { catch: true, ...tempoOptions });
+			if (t.isValid) success++; else failure++;
+		}
+	}
+
+	const elapsed = performance.now() - start;
+	const endHeap = process.memoryUsage().heapUsed;
+	const ops = iterations * data.length;
+
+	return {
+		label,
+		totalTimeMs: Number(elapsed.toFixed(2)),
+		opsPerSec: Math.round(ops / (elapsed / 1000)),
+		microSecPerOp: Number(((elapsed * 1000) / ops).toFixed(2)),
+		successCount: success,
+		failureCount: failure,
+		successRate: ((success / ops) * 100).toFixed(1) + '%',
+		heapDeltaMb: Number(((endHeap - startHeap) / 1024 / 1024).toFixed(2)),
+	};
+}
+
+// ── Run ──────────────────────────────────────────────────────────────────────
+
+const ITERATIONS = 500;
+
+console.log(`\n⏱  Tempo v3.3.0 Post-Refactor Benchmark  (${ITERATIONS} iterations × corpus size)\n`);
+
+// A. Baseline — stock config, base corpus (mirrors pre-refactor run)
+Tempo.init({ debug: 0, catch: true, timeZone: 'UTC' });
+const baseline = timedRun('A. Baseline (stock, 20-entry corpus)', baseCorpus, ITERATIONS, { timeZone: 'UTC' });
+
+// B. Baseline with all three Tempo modes using BenchmarkModule
+Tempo.init({ debug: 0, catch: true, timeZone: 'UTC' });
+const moduleResults = BenchmarkModule.run(Tempo, {
+	data: baseCorpus,
+	iterations: ITERATIONS,
+	modes: ['auto', 'defer', 'strict'],
+	baseline: true,
+});
+
+// C. Localized modifier corpus — exercises the new registry.modifiers code path
+const localizedConfig = {
+	locale: 'fr-FR',
+	debug: 0,
+	catch: true,
+	timeZone: 'UTC',
+	registry: {
+		modifiers: {
+			'>': ['prochain', 'suivant'],
+			'<': ['dernier', 'passé'],
+			'=': ['ce', 'cette'],
+		}
+	}
+};
+Tempo.init(localizedConfig as any);
+const localized = timedRun('C. Localized fr-FR modifiers (8-entry corpus)', frCorpus, ITERATIONS, {});
+
+// ── Output ───────────────────────────────────────────────────────────────────
+
+const output = {
+	runAt: new Date().toISOString(),
+	version: '3.3.0',
+	iterations: ITERATIONS,
+	baselineRaw: baseline,
+	moduleResults,
+	localizedModifiers: localized,
+};
+
+// Pretty console table
+console.log('── Module-based comparison (matches pre-refactor format) ──');
+BenchmarkModule.printTable(moduleResults);
+
+console.log('\n── Baseline (manual, matches pre-refactor corpus exactly) ──');
+console.table([{
+	'Engine': baseline.label,
+	'Total Time (ms)': baseline.totalTimeMs,
+	'µs / Op': baseline.microSecPerOp,
+	'ops/sec': baseline.opsPerSec,
+	'Success Rate': baseline.successRate,
+	'Heap Delta (MB)': baseline.heapDeltaMb,
+}]);
+
+console.log('\n── New: Localized modifier throughput ──');
+console.table([{
+	'Engine': localized.label,
+	'Total Time (ms)': localized.totalTimeMs,
+	'µs / Op': localized.microSecPerOp,
+	'ops/sec': localized.opsPerSec,
+	'Success Rate': localized.successRate,
+	'Heap Delta (MB)': localized.heapDeltaMb,
+}]);
+
+// Save to file
+const outPath = path.join(__dirname, 'benchmark-results-v3.3.0.json');
+fs.writeFileSync(outPath, JSON.stringify(output, null, 2));
+console.log(`\n✅  Results saved to ${outPath}\n`);
diff --git a/packages/tempo/bench/benchmark-results-v3.3.0.json b/packages/tempo/bench/benchmark-results-v3.3.0.json
new file mode 100644
index 00000000..1082ac5f
--- /dev/null
+++ b/packages/tempo/bench/benchmark-results-v3.3.0.json
@@ -0,0 +1,63 @@
+{
+  "runAt": "2026-06-21T03:09:07.682Z",
+  "version": "3.3.0",
+  "iterations": 500,
+  "baselineRaw": {
+    "label": "A. Baseline (stock, 20-entry corpus)",
+    "totalTimeMs": 15517.8,
+    "opsPerSec": 644,
+    "microSecPerOp": 1551.78,
+    "successCount": 10000,
+    "failureCount": 0,
+    "successRate": "100.0%",
+    "heapDeltaMb": 113.02
+  },
+  "moduleResults": [
+    {
+      "name": "Native Date",
+      "totalTimeMs": 2.92,
+      "microSecPerOp": 0.29,
+      "successCount": 2500,
+      "failureCount": 7500,
+      "successRate": "25.0%",
+      "heapUsedDeltaMb": "1.08"
+    },
+    {
+      "name": "Tempo (mode: auto)",
+      "totalTimeMs": 15524.01,
+      "microSecPerOp": 1552.4,
+      "successCount": 10000,
+      "failureCount": 0,
+      "successRate": "100.0%",
+      "heapUsedDeltaMb": "10.34"
+    },
+    {
+      "name": "Tempo (mode: defer)",
+      "totalTimeMs": 15089.25,
+      "microSecPerOp": 1508.93,
+      "successCount": 10000,
+      "failureCount": 0,
+      "successRate": "100.0%",
+      "heapUsedDeltaMb": "-22.66"
+    },
+    {
+      "name": "Tempo (mode: strict)",
+      "totalTimeMs": 15784.87,
+      "microSecPerOp": 1578.49,
+      "successCount": 10000,
+      "failureCount": 0,
+      "successRate": "100.0%",
+      "heapUsedDeltaMb": "56.53"
+    }
+  ],
+  "localizedModifiers": {
+    "label": "C. Localized fr-FR modifiers (8-entry corpus)",
+    "totalTimeMs": 11330.81,
+    "opsPerSec": 353,
+    "microSecPerOp": 2832.7,
+    "successCount": 4000,
+    "failureCount": 0,
+    "successRate": "100.0%",
+    "heapDeltaMb": -9.07
+  }
+}
\ No newline at end of file

From 6ceb8edc699e6aa3c870e1d8904dd3bf4e20f5d6 Mon Sep 17 00:00:00 2001
From: Michael McRae <michael@magmacomputing.com.au>
Date: Sun, 21 Jun 2026 18:55:14 +1000
Subject: [PATCH 6/6] PR 2nd review

---
 packages/tempo/bench/bench.v3.3.0.ts          |  4 +-
 packages/tempo/bench/modifiers.ts             | 11 ++-
 packages/tempo/doc/releases/v3.x.md           | 71 ++++++++++++++++
 packages/tempo/doc/tempo.plugin.md            |  1 +
 packages/tempo/src/engine/engine.lexer.ts     | 17 ++--
 packages/tempo/src/engine/engine.term.ts      | 80 ++++++++++++++-----
 .../tempo/src/plugin/term/term.quarter.ts     |  6 ++
 packages/tempo/src/plugin/term/term.season.ts |  6 ++
 packages/tempo/src/plugin/term/term.util.ts   |  2 +-
 packages/tempo/src/tempo.class.ts             | 27 ++++---
 packages/tempo/test/engine/modifiers.test.ts  | 22 +++--
 11 files changed, 204 insertions(+), 43 deletions(-)

diff --git a/packages/tempo/bench/bench.v3.3.0.ts b/packages/tempo/bench/bench.v3.3.0.ts
index b3618538..48251fe7 100644
--- a/packages/tempo/bench/bench.v3.3.0.ts
+++ b/packages/tempo/bench/bench.v3.3.0.ts
@@ -3,8 +3,8 @@
  *
  * Compares three configurations:
  *   A. Baseline: stock Tempo, same corpus as pre-refactor
- *   B. Localized modifiers: registry.modifiers + locale:'fr-FR' active
- *   C. English relative strings through the new modifier path
+ *   B. Module-based comparison using BenchmarkModule across auto/defer/strict modes
+ *   C. Localized fr-FR modifiers through the new registry.modifiers code path
  */
 import '../bin/temporal-polyfill.js';
 import { Tempo } from '../src/tempo.index.js';
diff --git a/packages/tempo/bench/modifiers.ts b/packages/tempo/bench/modifiers.ts
index 090f7a39..ca800766 100644
--- a/packages/tempo/bench/modifiers.ts
+++ b/packages/tempo/bench/modifiers.ts
@@ -4,10 +4,17 @@ import { Tempo } from '../src/tempo.class.js';
 const ITERATIONS = 100_000;
 
 function runBenchmark(name: string, expression: string) {
+	Tempo.init({ debug: 0, catch: true, timeZone: 'UTC' });
+
+	// Warm-up pass for JIT stabilization
+	const warmupIterations = Math.min(ITERATIONS, 1000);
+	for (let i = 0; i < warmupIterations; i++)
+		new Tempo(expression, { catch: true });
+
 	const start = performance.now();
-	for (let i = 0; i < ITERATIONS; i++) {
+	for (let i = 0; i < ITERATIONS; i++)
 		new Tempo(expression);
-	}
+
 	const end = performance.now();
 	const duration = end - start;
 	const opsPerSec = Math.round((ITERATIONS / duration) * 1000);
diff --git a/packages/tempo/doc/releases/v3.x.md b/packages/tempo/doc/releases/v3.x.md
index 22aae295..8aaf6b81 100644
--- a/packages/tempo/doc/releases/v3.x.md
+++ b/packages/tempo/doc/releases/v3.x.md
@@ -1,5 +1,76 @@
 # 📜 Version 3.x History
 
+## [v3.3.0] - 2026-06-21
+
+### ✨ What's New — Localized Modifier Registry
+
+Tempo's relative-date keywords (`next`, `last`, `this`, `ago`, `hence`) were previously hardcoded as English-only constructs built into the core regex engine. **v3.3.0 opens this up completely.**
+
+You can now register your own locale-specific words for any directional operator using `registry.modifiers`. These words integrate transparently with all standard parsing paths — prefix position, suffix position, and the high-performance `#` slick shorthand:
+
+```typescript
+Tempo.init({
+  locale: 'fr-FR',            // teaches Tempo French months & weekdays via Intl
+  registry: {
+    modifiers: {
+      '>': ['prochain', 'suivant'],   // "next" synonyms
+      '<': ['dernier', 'passé'],      // "last / previous" synonyms
+      '=': ['ce', 'cette'],           // "this" synonyms
+    }
+  }
+});
+
+new Tempo('vendredi prochain');    // ✅ "next Friday" — fully French
+new Tempo('1 mai prochain');       // ✅ "next May 1st"
+new Tempo('#qtr.dernier');         // ✅ "previous quarter" via slick shorthand
+```
+
+English keywords (`next`, `last`, `ago`, `hence`, `this`) remain active by default and are **additively merged** — you never lose built-in behaviour when adding your own.
+
+### 🏗️ Internal Refactoring
+
+- **Frozen Default Registry Fixed**: The internal `Default` configuration object is wrapped in a deep-freeze Proxy (`secure()`). Previously, every `Tempo.init()` call silently failed to write `formats`, `locales`, and `modifiers` into the frozen registry sub-object, logging three `setProperty` warnings per call and abandoning the writes. The registry is now correctly shallow-cloned into a mutable copy on initialization.
+
+- **Lexer Token Cleanup**: All hardcoded English modifier keywords have been stripped from the core regex tokens (`Match.modifier`, `Match.shorthand`, `Match.slick`). The engine now operates purely on symbolic operators (`>`, `<`, `=`, `+`, `-`) internally and resolves all natural-language words through the registry at runtime.
+
+- **Pre-filter Guard Accuracy**: Refined the numeric-safety guard bypass to trigger only when the input *actually contains* a registered modifier keyword. Previously the guard was bypassed unconditionally whenever modifier config was present, which could silently accept invalid nanosecond epoch strings.
+
+### ⚡ Slick Modifier Semantics
+
+Localized slick modifiers behave identically to their symbolic counterparts. `#qtr.prochain` is an exact alias for `#qtr.>`:
+
+- From **inside** Q2 (any day from April 1 to June 29) → **July 1** (start of Q3)
+- From **June 30** (last day of Q2) → **July 1** (start of Q3)
+- From **July 1** (first day of Q3) → **October 1** (start of Q4)
+
+This mirrors how `next Friday` works: from any non-Friday you get the very next Friday; if you are already on Friday, you get the *following* Friday. Fully deterministic — "next" always means *"the start of the next occurrence of this term"*.
+
+---
+
+## [v3.2.3] - 2026-06-20
+
+### ✨ What's New — Project Scaffolding
+
+- **`tempo.config.ts` Pattern**: Introduced centralized project configuration via a discoverable `tempo.config.ts` / `tempo.config.js` file. This mirrors the `vite.config.ts` / `tailwind.config.js` convention — one file, one place, loaded once.
+- **`Tempo.bootstrap()`**: A new async entry point that auto-discovers and loads your `tempo.config.ts` before any domain logic runs. Safe to `await` at application startup.
+- **CLI Scaffold**: `npx @magmacomputing/tempo scaffold:all` bootstraps a `tempo.config.ts` and HTML sandbox into your project in seconds.
+
+---
+
+## [v3.2.2] - 2026-06-18
+
+### ✨ What's New
+
+- **Compact Date Tokens**: New 6-digit compact format tokens `{dmy6}`, `{mdy6}`, `{ymd6}` (e.g. `200626`), plus ISO week-of-year helpers `{yywy}` and `{yyww}`.
+- **`{wy}` Rename**: The former `{ww}` token is now `{wy}` (week-of-year) to eliminate visual ambiguity with structural format tokens.
+
+### 🏗️ Internal Refactoring
+
+- **Recursive `deepMerge` Hardened**: The Intl options merge pipeline now uses a fully recursive `deepMerge` rather than a shallow spread, preventing nested keys like `intl.dateTimeFormat` from clobbering `intl.relativeTimeFormat`.
+- **Prototype Pollution Guards**: Added strict guards against `__proto__`, `constructor`, and `prototype` key assignments in `deepMerge` and `deepFreeze` utilities.
+
+---
+
 ## [v3.2.1] - 2026-06-17
 
 ### ✨ What's New
diff --git a/packages/tempo/doc/tempo.plugin.md b/packages/tempo/doc/tempo.plugin.md
index 2a696dc3..d98e518d 100644
--- a/packages/tempo/doc/tempo.plugin.md
+++ b/packages/tempo/doc/tempo.plugin.md
@@ -144,6 +144,7 @@ When building plugins that perform complex parsing or logic, follow Tempo's **"F
 
 - **Strict Mode (Default)**: If your plugin encounters a terminal error (e.g., invalid input that cannot be recovered), you should `throw` a descriptive error.
 - **Catch Mode**: Respect the user's `catch` configuration. If `this.config.catch` is `true`, instead of throwing, you should log a warning using `this.warn()` and return a sensible fallback (or the original input).
+- **Configuration Dependencies**: *You* are responsible for managing missing configuration keys that your plugin depends on. The core engine will not validate your plugin's specific requirements. If a required config key is missing (e.g., `sphere` for a Season plugin), either provide a reasonable default fallback value or warn the user explicitly using `this.warn()`. Do not make assumptions that lead to silent failures.
 
 ```typescript
 // Example within a plugin instance method
diff --git a/packages/tempo/src/engine/engine.lexer.ts b/packages/tempo/src/engine/engine.lexer.ts
index c99c38c0..169e59bd 100644
--- a/packages/tempo/src/engine/engine.lexer.ts
+++ b/packages/tempo/src/engine/engine.lexer.ts
@@ -1,6 +1,7 @@
 import '#library/temporal.polyfill.js';
 import { isString, isEmpty, isUndefined, isDefined, isTemporal, isInstant } from '#library/assertion.library.js';
 import { ownKeys, ownEntries } from '#library/primitive.library.js';
+import { asArray } from '#library/coercion.library.js';
 
 import { pad, singular } from '#library/string.library.js';
 import { Match, enums, isTempo, logError, logWarn, logDebug } from '#tempo/support';
@@ -76,17 +77,23 @@ export function prefix(str: any): any {
 }
 
 /** resolve a relative modifier (+, -, <, >, =, etc) */
-export function parseModifier({ mod, adjust, offset, period }: Lexer.GroupModifier, config: any = {}) {
-	adjust = Math.abs(adjust);
+export function normalizeModifier(mod: string, config: any = {}): string {
 	if (mod && config?.registry?.modifiers) {
 		const norm = mod.toLowerCase().trim().normalize('NFD').replace(/[\u0300-\u036f]/g, "");
 		for (const [sym, words] of Object.entries(config.registry.modifiers)) {
-			if ((words as string[]).map(w => w.toLowerCase().trim().normalize('NFD').replace(/[\u0300-\u036f]/g, "")).includes(norm)) {
-				mod = sym as t.Modifier;
-				break;
+			if (asArray(words as string[])
+				.map(w => w.toLowerCase().trim().normalize('NFD').replace(/[\u0300-\u036f]/g, ""))
+				.includes(norm)) {
+				return sym;
 			}
 		}
 	}
+	return mod;
+}
+
+export function parseModifier({ mod, adjust, offset, period }: Lexer.GroupModifier, config: any = {}) {
+	adjust = Math.abs(adjust);
+	mod = normalizeModifier(mod as string, config) as any;
 
 	switch (mod) {
 		case undefined:
diff --git a/packages/tempo/src/engine/engine.term.ts b/packages/tempo/src/engine/engine.term.ts
index 4e44898c..55f98c83 100644
--- a/packages/tempo/src/engine/engine.term.ts
+++ b/packages/tempo/src/engine/engine.term.ts
@@ -5,7 +5,7 @@ import { asArray } from '#library/coercion.library.js';
 import { sym, TermError, getLargestUnit, SCHEMA, Match, isTempo } from '#tempo/support';
 import { getRange, getTermRange, resolveTermShift, findTermPlugin } from '../plugin/term/term.util.js';
 import { getHost } from '../plugin/plugin.util.js';
-import { parseModifier } from './engine.lexer.js';
+import { parseModifier, normalizeModifier } from './engine.lexer.js';
 
 import type { Tempo } from '../tempo.class.js';
 import type { TempoTermType } from '../plugin/term/term.type.js';
@@ -29,20 +29,23 @@ const toZdt = (v: any): Temporal.ZonedDateTime => isTempo(v) ? v.toDateTime() :
 export function resolveTermMutation(Tempo: TempoTermType, instance: Tempo, mutate: string, unit: string, offset: any, zdt: Temporal.ZonedDateTime): Temporal.ZonedDateTime | null {
 	if (!isZonedDateTime(zdt)) return zdt;
 
-	const [termPart, rangePart] = unit.startsWith('#')
-		? unit.slice(1).split('.')
-		: [unit, undefined];
+	let termPart = unit;
+	let rangePart: string | undefined;
+	if (unit.startsWith('#')) {
+		const parts = unit.slice(1).split('.');
+		termPart = parts[0];
+		if (parts.length > 1) rangePart = parts.slice(1).join('.');
+	} else if (unit.includes('.')) {
+		const parts = unit.split('.');
+		termPart = parts[0];
+		if (parts.length > 1) rangePart = parts.slice(1).join('.');
+	}
 
 	const state = isTempo(instance)
 		? (instance as any)[sym.$Internal]?.()
 		: (instance as any);
 	const termObj = findTermPlugin(termPart, state);
 
-	if (!termObj) {
-		Tempo?.[TermError]?.(instance.config, unit);
-		return null;
-	}
-
 	const [tz, cal] = getTemporalIds(zdt);
 
 	// Slick Shorthand Parsing (e.g. #qtr.>2, #zodiac.<)
@@ -79,15 +82,8 @@ export function resolveTermMutation(Tempo: TempoTermType, instance: Tempo, mutat
 			const hasNbr = isNumeric(groups.sh_nbr);
 			mod = hasMod ? groups.sh_mod : undefined;
 
-			if (mod && state.config.registry?.modifiers) {
-				const norm = mod.toLowerCase().trim();
-				for (const [sym, words] of Object.entries(state.config.registry.modifiers)) {
-					if ((words as string[]).includes(norm)) {
-						mod = sym;
-						break;
-					}
-				}
-			}
+			if (mod && state.config.registry?.modifiers)
+				mod = normalizeModifier(mod, state.config);
 
 			nbr = hasNbr ? Number(groups.sh_nbr) : 1;
 			rKey = (groups.sh_unit && groups.sh_unit.length > 0) ? groups.sh_unit : (hasMod ? undefined : rKey);
@@ -95,6 +91,51 @@ export function resolveTermMutation(Tempo: TempoTermType, instance: Tempo, mutat
 		}
 	}
 
+	if (!termObj) {
+		const termNorm = termPart.toLowerCase();
+		const mappedWkd = state.parse?.weekdayMap?.[termNorm];
+		let wkdValue = mappedWkd?.value;
+
+		if (wkdValue === undefined) {
+			const engWkd = ['xxx', 'mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun'];
+			const idx = engWkd.findIndex(w => termNorm.startsWith(w));
+			if (idx !== -1) wkdValue = idx;
+		}
+
+		if (wkdValue !== undefined && mod) {
+			const targetDow = wkdValue;
+			const currentDow = zdt.dayOfWeek;
+			let diff = 0;
+
+			if (mod === '>' || mod === 'next') {
+				diff = (targetDow - currentDow + 7) % 7 || 7;
+			} else if (mod === '<' || mod === 'last' || mod === 'prev') {
+				diff = -((currentDow - targetDow + 7) % 7 || 7);
+			} else if (mod === '>=') {
+				diff = (targetDow - currentDow + 7) % 7;
+			} else if (mod === '<=') {
+				diff = -((currentDow - targetDow + 7) % 7);
+			} else if (mod === '=') {
+				diff = (targetDow - currentDow + 7) % 7;
+			} else {
+				Tempo?.[TermError]?.(instance.config, unit);
+				return null;
+			}
+
+			if (nbr > 1) {
+				if (diff > 0) diff += (nbr - 1) * 7;
+				else if (diff < 0) diff -= (nbr - 1) * 7;
+				else if (diff === 0 && (mod === '>=' || mod === '<=')) {
+					diff = mod === '>=' ? (nbr - 1) * 7 : -(nbr - 1) * 7;
+				}
+			}
+			return zdt.add({ days: diff }).withTimeZone(tz).withCalendar(cal);
+		}
+
+		Tempo?.[TermError]?.(instance.config, unit);
+		return null;
+	}
+
 	// 0. Handle relative .add() — preserving position within the target range
 	if (mutate === 'add') {
 		const slickParsed = isDefined(slickStr);
@@ -342,7 +383,7 @@ export function resolveTermMutation(Tempo: TempoTermType, instance: Tempo, mutat
 			// Treat explicit modifiers and + / - as shifters. Numeric repeat counts
 			// without an explicit modifier (e.g. `2q2`) are handled as inclusive
 			// searches and should not be treated as shifters.
-			const isShifter = (mod === '>' || mod === '<' || mod === '+' || mod === '-');
+			const isShifter = (mod === '>' || mod === '<' || mod === '>=' || mod === '<=' || mod === '+' || mod === '-');
 
 			const compare = (r: any) => {
 				const start = toZdt(r.start).epochNanoseconds as bigint;
@@ -393,6 +434,7 @@ export function resolveTermMutation(Tempo: TempoTermType, instance: Tempo, mutat
 					const start = toZdt(m.start).epochNanoseconds;
 					const end = toZdt(m.end).epochNanoseconds;
 					const cursor = jump.epochNanoseconds;
+					if (mod === '>=' || mod === '<=') return true;
 					if (direction > 0) return start >= cursor;
 					return end <= cursor;
 				});
diff --git a/packages/tempo/src/plugin/term/term.quarter.ts b/packages/tempo/src/plugin/term/term.quarter.ts
index 4bfd848e..cdf4fc7c 100644
--- a/packages/tempo/src/plugin/term/term.quarter.ts
+++ b/packages/tempo/src/plugin/term/term.quarter.ts
@@ -1,4 +1,5 @@
 import { defineTerm, getTermRange, defineRange, resolveCycleWindow } from './term.util.js';
+import { logWarn } from '../../support/support.util.js';
 import { COMPASS } from '../../support/support.enum.js';
 import { isNumber } from '#library/assertion.library.js';
 import { asArray } from '#library';
@@ -19,6 +20,11 @@ const groups = defineRange([
 
 /** resolve the full candidate list for the current context */
 function resolve(t: Tempo, anchor?: any): any[] {
+	if (t.config.sphere === undefined && anchor?.sphere === undefined) {
+		logWarn(`[tempo] QuarterTerm requires 'sphere' configuration (e.g. Tempo.init({ sphere: 'north' }) or { sphere: 'south' }).`, t.config);
+		return [];
+	}
+
 	const list = resolveCycleWindow(t, groups, { anchor, groupBy: ['sphere'] });
 
 	list.forEach(itm => {
diff --git a/packages/tempo/src/plugin/term/term.season.ts b/packages/tempo/src/plugin/term/term.season.ts
index 39a5c969..a7be64b0 100644
--- a/packages/tempo/src/plugin/term/term.season.ts
+++ b/packages/tempo/src/plugin/term/term.season.ts
@@ -1,4 +1,5 @@
 import { getTermRange, defineTerm, defineRange, resolveCycleWindow } from './term.util.js';
+import { logWarn } from '../../support/support.util.js';
 import { COMPASS } from '../../support/support.enum.js';
 import type { Tempo } from '../../tempo.class.js';
 
@@ -19,6 +20,11 @@ const groups = defineRange([
 
 /** resolve the full candidate list for the current context */
 function resolve(t: Tempo, anchor?: any) {
+	if (t.config.sphere === undefined && anchor?.sphere === undefined) {
+		logWarn(`[tempo] SeasonTerm requires 'sphere' configuration (e.g. Tempo.init({ sphere: 'north' }) or { sphere: 'south' }).`, t.config);
+		return [];
+	}
+
 	const list = resolveCycleWindow(t, groups, { anchor, groupBy: ['group', 'sphere'], group: 'meteorological' });
 
 	return list;
diff --git a/packages/tempo/src/plugin/term/term.util.ts b/packages/tempo/src/plugin/term/term.util.ts
index 22fa9001..5ccb40c4 100644
--- a/packages/tempo/src/plugin/term/term.util.ts
+++ b/packages/tempo/src/plugin/term/term.util.ts
@@ -342,7 +342,7 @@ export function resolveCycleWindow(source: Tempo | any, template: Range[] | Reco
 
 	// Ensure chronological order for reliable anchor/window calculation
 	list = [...list]; // Defensive copy to avoid mutating the original template
-	sortKey(list, 'month', 'day', 'hour', 'minute', 'second', 'millisecond', 'microsecond', 'nanosecond');
+	sortKey(list, 'year', 'month', 'day', 'hour', 'minute', 'second', 'millisecond', 'microsecond', 'nanosecond');
 
 	// 2. Resolve Window (Sub-Yearly vs Yearly)
 	const unit = getLargestUnit(list);
diff --git a/packages/tempo/src/tempo.class.ts b/packages/tempo/src/tempo.class.ts
index 94ef4018..dda85358 100644
--- a/packages/tempo/src/tempo.class.ts
+++ b/packages/tempo/src/tempo.class.ts
@@ -324,10 +324,10 @@ export class Tempo {
 
 		// Apply options using extendState
 		const patternsDirty = extendState(shape, mergedOptions);
-		if (patternsDirty) {
-			setPatterns(shape);
-			if (shape.config.scope === 'local')
-				this[$buildGuard](shape);
+		let needsRebuild = patternsDirty;
+
+		if (patternsDirty && shape.config.scope === 'local') {
+			this[$buildGuard](shape);
 		}
 
 		// Side-effects
@@ -338,12 +338,22 @@ export class Tempo {
 		} else {
 			shape.config.sphere = newSphere;
 		}
+
+		const oldLayout = shape.parse.layout;
 		Tempo._swapLayout(shape);
+		if (oldLayout !== shape.parse.layout) needsRebuild = true;
 
-		if (isDefined(shape.parse.event)) this[$setEvents](shape, undefined, false);
-		if (isDefined(shape.parse.period)) this[$setPeriods](shape, undefined, false);
+		if (isDefined(shape.parse.event)) {
+			this[$setEvents](shape, undefined, false);
+			needsRebuild = true;
+		}
+		if (isDefined(shape.parse.period)) {
+			this[$setPeriods](shape, undefined, false);
+			needsRebuild = true;
+		}
 
-		setPatterns(shape);
+		if (needsRebuild)
+			setPatterns(shape);
 	}
 
 	/** support "Global Discovery" of user-options */
@@ -467,9 +477,8 @@ export class Tempo {
 			(this[$Internal]() as any)[$guard] = guard;
 		}
 
-		if (this[$Internal]() === _global) {
+		if (!targetState && this[$Internal]() === _global)
 			setPatterns(this[$Internal]());
-		}
 	}
 
 	/** @internal resolve a global discovery config object by symbol key */
diff --git a/packages/tempo/test/engine/modifiers.test.ts b/packages/tempo/test/engine/modifiers.test.ts
index 4d86c55c..575b9aad 100644
--- a/packages/tempo/test/engine/modifiers.test.ts
+++ b/packages/tempo/test/engine/modifiers.test.ts
@@ -4,6 +4,7 @@ describe('Localized Modifiers', () => {
 
 	test('should parse localized prefix and suffix modifiers for weekdays', () => {
 		const config = defineConfig({
+			timeZone: 'UTC',
 			registry: {
 				modifiers: {
 					'>': ['prochain'],
@@ -12,7 +13,8 @@ describe('Localized Modifiers', () => {
 			}
 		});
 
-		const now = new Tempo('2026-06-20T12:00:00+10:00', config); // Saturday
+		// anchor: 2026-06-20T02:00:00Z → Saturday in UTC
+		const now = new Tempo('2026-06-20T12:00:00+10:00', config);
 
 		const prochainFriday = new Tempo('prochain friday', { ...config, anchor: now });
 		expect(prochainFriday.dow).toBe(5);
@@ -25,6 +27,7 @@ describe('Localized Modifiers', () => {
 
 	test('should parse localized prefix and suffix modifiers for explicit dates', () => {
 		const config = defineConfig({
+			timeZone: 'UTC',
 			registry: {
 				modifiers: {
 					'>': ['prochain'],
@@ -33,8 +36,9 @@ describe('Localized Modifiers', () => {
 			}
 		});
 
+		// anchor: 2026-06-20T02:00:00Z → Saturday in UTC
 		const now = new Tempo('2026-06-20T12:00:00+10:00', config);
-		
+
 		const nextMay = new Tempo('1 May prochain', { ...config, anchor: now });
 		if (nextMay.yy !== 2027) throw new Error("nextMay.yy is " + nextMay.yy + " month: " + nextMay.mm + " day: " + nextMay.day);
 		expect(nextMay.mm).toBe(5);
@@ -54,6 +58,7 @@ describe('Localized Modifiers', () => {
 
 	test('should respect partial match fallback sorting (longest-match first)', () => {
 		const config = defineConfig({
+			timeZone: 'UTC',
 			registry: {
 				modifiers: {
 					'>': ['dans', 'dans la', 'en']
@@ -61,6 +66,7 @@ describe('Localized Modifiers', () => {
 			}
 		});
 
+		// anchor: 2026-06-20T02:00:00Z → Saturday in UTC
 		const now = new Tempo('2026-06-20T12:00:00+10:00', config);
 
 		const futureDate = new Tempo('1 May dans la', { ...config, anchor: now });
@@ -71,6 +77,8 @@ describe('Localized Modifiers', () => {
 
 	test('should map shorthand localized terms correctly', () => {
 		const config = defineConfig({
+			timeZone: 'UTC',
+			sphere: 'north',
 			registry: {
 				modifiers: {
 					'>': ['prochain']
@@ -78,10 +86,14 @@ describe('Localized Modifiers', () => {
 			}
 		});
 
-		const now = new Tempo('2026-06-20T12:00:00+10:00', config);
+		// anchor: Saturday June 20 in UTC (pure UTC timestamp to avoid tz-leak into term resolver)
+		const now = new Tempo('2026-06-20T12:00:00Z', config);
 
-		// shorthand shift using localized term
+		// shorthand shift using localized term.
+		// '#qtr.prochain' (>) is equivalent to '#qtr.next' / '#qtr.>'.
+		// From anywhere inside Q2, '>' resolves to July 1 (start of Q3).
+		// It only advances further (Oct 1) once the anchor is already ON July 1.
 		const nextQtr = new Tempo('#qtr.prochain', { ...config, anchor: now });
-		expect(nextQtr.mm).toBeGreaterThan(6);
+		expect(nextQtr.mm).toBeGreaterThan(6); // July (7) or later = Q3+
 	});
 });