memorio 4.7.0 → 4.7.3

package/README.md

@@ -1,6 +1,6 @@
 # 🧠 memorio
 
-![image](https://raw.githubusercontent.com/passariello/container/refs/heads/main/memorio/banner.svg)
+![banner](https://raw.githubusercontent.com/passariello/container/refs/heads/main/memorio/banner.svg)
 
 [![npm version](https://img.shields.io/npm/v/memorio.svg)](https://npmjs.com/package/memorio)
 [![npm downloads](https://img.shields.io/npm/dm/memorio.svg)](https://npmjs.com/package/memorio)
@@ -13,197 +13,143 @@
 ![Tests](https://img.shields.io/badge/tests-101%20passed-green)
 ![License](https://img.shields.io/badge/License-MIT-gray)
 
-**State + Observer + Store + IDB. One import. Zero config.**
+### One import. Global state, persistence, and a IndexedDB layer - done.
 
-Memorio is a universal, cross-platform state management library for JavaScript and TypeScript. Reactive state, persistent store, session cache, IndexedDB, observer system, React hook, devtools, and logger — all from one import, zero dependencies.
+```javascript
+import 'memorio'
 
----
+state.user = { name: 'Sara' }   // reactive, everywhere, instantly
+```
 
-## ✨ Why memorio?
+No provider tree. No reducers. No actions to dispatch before you can change a number. If you've ever set up a global store for an app that just needed *"a value, shared, that updates the UI when it changes,"* memorio is the toolkit for that thirty-second job - and it keeps growing with you: session storage, a cache, typed IndexedDB tables, an observer system, a React hook, devtools, and a change logger, all sharing one mental model.
 
-| Feature | 🔥 memorio | Redux | Zustand |
-|---|---|---|---|
-| **Setup** | ✅ **1 import** | ❌ Boilerplate hell | ⚠️ Moderate |
-| **Dependencies** | ✅ **Zero** | ❌ Many | ⚠️ Few |
-| **TypeScript** | ✅ Native | ✅ Yes | ✅ Yes |
-| **Binary storage** | ✅ Built-in IDB | ❌ Add-on | ❌ Add-on |
-| **Observer** | ✅ Built-in | ❌ Add-on | ❌ Add-on |
-| **DevTools** | ✅ Built-in + dphelper-manager | ⚠️ Extension | ⚠️ Extension |
-| **Edge runtime** | ✅ Workers, Deno | ❌ Limited | ❌ Limited |
-| **Learning curve** | ✅ **5 minutes** | ❌ Hours | ⚠️ 30 min |
-| **Boilerplate** | ✅ **None** | ❌ Tons | ⚠️ Some |
-| **React support** | ✅ `useObserver` hook | ✅ `connect` | ✅ `useSyncExternalStore` |
-| **Context isolation** | ✅ Multi-tenant | ⚠️ Manual | ⚠️ Manual |
+---
+
+## Table of Contents
 
-Zero dependencies. Lightweight. One import.
+1. [Is this for you?](#is-this-for-you)
+2. [Installation](#installation)
+3. [Quick Start](#quick-start)
+4. [API Reference](#api-reference)
+5. [Typed Stores](#typed-stores)
+6. [Schema Validation](#schema-validation)
+7. [Cross-Platform Behavior](#cross-platform-behavior)
+8. [Context Isolation (multi-tenant)](#context-isolation-multi-tenant)
+9. [Security](#security)
+10. [License](#license)
 
 ---
 
-## 🚀 Features
+## Is this for you?
 
-| | |
-|---|---|
-| **`state`** | Reactive, Proxy-based volatile state |
-| **`store`** | localStorage persistence (survives refresh) |
-| **`session`** | sessionStorage (dies with tab) |
-| **`cache`** | In-memory fastest cache |
-| **`idb`** | IndexedDB with typed tables, structured and async |
-| **`observer`** | Legacy object watcher for vanilla JS |
-| **`useObserver`** | React hook with auto-discovery |
-| **`dispatch`** | Event system: listen, emit, subscribe |
-| **`devtools`** | Inspect everything in console |
-| **`logger`** | Auto-log every state change with timestamps |
-| **Context isolation** | Per-request / multi-tenant namespace |
-| **Platform detection** | `isBrowser`, `isNode`, `isDeno`, `isEdge` |
-
-No Zustand. No Redux. No provider boilerplate.
-**Import → assign → done.**
+memorio is built for speed of thought: you think "I need this value everywhere," you write one line, it works. That's the entire pitch - and it's a real one, not a rewritten complaint about how much Redux boilerplate you've had to write.
+
+**Reach for memorio when:**
+- You want state that's simply *there* - no store setup, no provider wrapping your app.
+- You want `localStorage`, `sessionStorage`, and `IndexedDB` behind one consistent API instead of learning three.
+- You're prototyping, building an internal tool, or shipping something small-to-medium where iteration speed matters more than architectural ceremony.
+
+**Reach for something else when:**
+- You need every state path statically type-checked against every observer - memorio's `state.foo.bar` and `observer('state.foo.bar', ...)` are connected by a string, not by the compiler, so a rename won't be caught for you. However, if you want compiler-checked state access, use `memorio.typed<T>()` (see [Typed Stores](#typed-stores)) which gives you full static types on the global `state` proxy. For runtime validation as well, combine with `memorio.registerSchema()` (see [Schema Validation](#schema-validation)).
+- You need Redux-style middleware, action logs, or time-travel debugging as a hard requirement for a large team - those tools exist because that discipline solves real problems at scale, not because their authors enjoy boilerplate. Memorio logs through `memorio.logger` and inspects via `memorio.devtools`, but doesn't have Redux DevTools time-travel.
+- Your isolation requirements are a security boundary, not a convenience - see [Context Isolation](#context-isolation-multi-tenant) before you rely on it for that.
+
+Pick the right tool. memorio is at its best when the answer to "how much state architecture do I need here?" is genuinely "not much."
 
 ---
 
-## 📦 Installation
+## Installation
 
 ```bash
-# npm
 npm i memorio
+# pnpm add memorio
+# yarn add memorio
 
-# pnpm
-pnpm add memorio
-
-# yarn
-yarn add memorio
-
-# React peer dep (optional, React >= 16.8)
+# Optional - only if you use the React hook
 npm i react react-dom
 ```
 
 ---
 
-## 🎯 Quick Start
+## Quick Start
 
-### Global style (original)
+### Global style - the whole point of memorio
 
 ```typescript
-// import 'memorio' once at your app entry point
-import 'memorio'
+import 'memorio' // once, at your entry point
 
-// state is now available everywhere
 state.user = { name: 'Sara', role: 'admin' }
 state.counter++
-state.settings = { theme: 'dark', lang: 'it' }
 
-// React - automatic dependency discovery
 useObserver(
-  () => { console.debug('user changed:', state.user) },
+  () => console.debug('user changed:', state.user),
   [state.user]
 )
-
-// Vanilla JS - event system
-memorio.dispatch.listen('state.user', (event) => {
-  console.debug('user changed:', event.detail)
-})
 ```
 
-### Classic `import` style (new)
-
-Every module is also a named export. Same instances, explicit dependencies.
+### Named imports - same instances, explicit about it
 
 ```typescript
-// ESM
-import {
-  state,
-  store,
-  session,
-  cache,
-  idb,
-  observer,
-  useObserver,
-  dispatch,
-  memorio
-} from 'memorio'
+import { state, store, session, cache, idb, observer, useObserver, dispatch, memorio } from 'memorio'
 
 state.user = { name: 'Sara' }
 store.set('theme', 'dark')
-
-// CJS
-const { state, store, memorio } = require('memorio')
 ```
 
 ```tsx
-// React with named imports
-import { useObserver, state } from 'memorio'
-
 function Counter() {
   const [, forceUpdate] = useReducer(x => x + 1, 0)
-
   useObserver(forceUpdate, [state.counter])
-
   return <div>Count: {state.counter}</div>
 }
 ```
 
-Both styles share the exact same instances. Pick whichever fits your project.
+Two styles, one engine underneath - use whichever reads better in your codebase.
 
 ---
 
-## 📚 API Reference
-
-### `state` — Reactive volatile state
+## API Reference
 
-Global, Proxy-based, reactive. Access anywhere.
+### `state` - reactive, volatile, Proxy-based
 
 ```javascript
-// Set
 state.user = { name: 'Sara', role: 'admin' }
-state.items = [1, 2, 3]
-
-// Get
-const name = state.user.name    // 'Sara'
-
-// List all keys
-console.debug(state.list)         // ['user', 'items']
+const name = state.user.name
 
-// Remove one key
+state.list          // ['user', 'items', ...]
 state.remove('items')
-
-// Clear all
 state.removeAll()
 
-// Lock/unlock (prevents modifications)
+// Freeze a slice of state when you need to stop guessing who mutated it
 state.config = { maxUsers: 100 }
 state.config.lock()
-state.config.maxUsers = 200 // Error: state 'config' is locked
+state.config.maxUsers = 200   // throws: state 'config' is locked
 state.config.unlock()
 ```
 
-### `store` — Survives refresh
+### `store` - the value that survives a refresh
 
 ```javascript
 store.set('preferences', { theme: 'dark' })
-const prefs = store.get('preferences')     // { theme: 'dark' } or null
-store.remove('preferences')
-store.removeAll()
-console.debug(store.size(), 'chars stored')
-console.debug(store.isPersistent)         // true -> real localStorage
+store.get('preferences')      // { theme: 'dark' } or null
+store.isPersistent            // true when backed by real localStorage
 ```
 
-### `session` — Dies with tab
+### `session` - lives as long as the tab does
 
 ```javascript
 session.set('token', 'user-abc-123')
-const token = session.get('token')         // 'user-abc-123' or null
-session.removeAll()
+session.get('token')
 ```
 
-### `cache` — In-memory, disappears on refresh
+### `cache` - the fastest thing you own, gone on refresh
 
 ```javascript
 cache.set('temp', computeExpensiveResult())
-const result = cache.get('temp')           // undefined or the value
-cache.clear()                              // empty it all
+cache.get('temp')
 ```
 
-### `idb` — Structured & typed
+### `idb` - typed, async, structured tables without the ceremony
 
 ```javascript
 await idb.db.create('my-db')
@@ -212,7 +158,9 @@ await idb.data.set('my-db', 'users', { id: 1, name: 'Sara' })
 const user = await idb.data.get('my-db', 'users', 1)
 ```
 
-### `observer` — Object watcher (legacy)
+> IndexedDB is a browser-only primitive - see [Cross-Platform Behavior](#cross-platform-behavior) for what happens off the browser.
+
+### `observer` / `useObserver` - watch a path, react to it
 
 ```javascript
 observer('state.user', (newVal, oldVal) => {
@@ -220,133 +168,299 @@ observer('state.user', (newVal, oldVal) => {
 })
 ```
 
-### `useObserver` — React observer hook
+> Keys here are plain strings, not statically checked against `state`'s shape. Keep the observer near the code that shapes that state, and grep before you rename.
 
-```jsx
-import { useObserver, state } from 'memorio'
+### `dispatch` - the event bus underneath it all
 
-function Counter() {
-  const [, forceUpdate] = useReducer(x => x + 1, 0)
+```javascript
+memorio.dispatch.listen('state.user', (event) => console.debug(event.detail))
+memorio.dispatch.set('state.user', { detail: { name: 'Sara' } })
+```
 
-  useObserver(forceUpdate, [state.counter])
+### `devtools` - see everything, instantly
 
-  return <div>Count: {state.counter}</div>
-}
+```javascript
+memorio.devtools.inspect()
+memorio.devtools.stats()
+memorio.devtools.exportData()
 ```
 
-### `dispatch` — Event system
+Pairs with [dphelper-manager](https://chrome.google.com/webstore/detail/dphelper-manager-dev-tool/oppppldaoknfddeikfloonnialijngbk) for visual, time-travel inspection of your global state straight from devtools.
+
+### `logger` - a black box for every change
 
 ```javascript
-// Listen
-memorio.dispatch.listen('state.user', (event) => {
-  console.debug('user changed:', event.detail)
-})
+memorio.logger.configure({ enabled: true, logToConsole: true })
+memorio.logger.getHistory()
+```
 
-// Emit
-memorio.dispatch.set('state.user', { detail: { name: 'state.user' } })
+> It logs *everything* written to `state`/`store`/`session` - including anything sensitive you put there. Great for debugging, but don't leave it on unconditionally in production if secrets or PII pass through your state. See [Security](#security).
 
-// Remove
-memorio.dispatch.remove('state.user')
+---
+
+## Typed Stores
+
+`memorio.typed<T>()` returns the global `state` proxy cast to a TypeScript type `T`, giving you **compile-time** type safety on every access and mutation. The returned object is the *exact same* Proxy as `globalThis.state` — no duplication, no overhead.
+
+```typescript
+import 'memorio'
+
+interface AppState {
+  user: { name: string; age: number; email: string }
+  theme: 'light' | 'dark'
+  items: string[]
+}
+
+const app = memorio.typed<AppState>()
+
+// Type-checked at compile time:
+app.user = { name: 'Sara', age: 30, email: 'sara@test.com' }
+app.theme = 'dark'
+
+// TypeScript errors:
+// app.user = { name: 42 }            // age missing, name wrong type
+// app.theme = 'purple'               // not a valid literal
 ```
 
-### `devtools` — Inspect everything
+The same data is accessible via the global `state` proxy — `app` and `state` are identical instances:
 
-```javascript
-memorio.devtools.inspect()   // pretty-prints state, store, session, cache
-memorio.devtools.stats()     // { stateKeys, storeKeys, sessionKeys, ... }
-memorio.devtools.clear('state')
-memorio.devtools.exportData() // JSON snapshot
-$state  // console shortcut -> globalThis.state
+```typescript
+state.user = { name: 'Sara', age: 30, email: 'sara@test.com' }
+app.user.name   // 'Sara' — same Proxy
 ```
 
-> 💡 **Browser Extension**: When used with [dphelper-manager](https://chrome.google.com/webstore/detail/dphelper-manager-dev-tool/oppppldaoknfddeikfloonnialijngbk), Memorio's global state is automatically detected and visualized with time-travel debugging.
+For runtime safety (rejecting invalid values even when TypeScript isn't checking), combine with [Schema Validation](#schema-validation) below.
 
-### `logger` — Track every change
+See [Typed Stores docs](markdown/TYPED.md) for full examples.
 
-```javascript
-memorio.logger.configure({ enabled: true, logToConsole: true })
-memorio.logger.getHistory()   // [{ timestamp, module, action, path, value }, ...]
-memorio.logger.getStats()     // { total, state, set, get, ... }
-memorio.logger.exportLogs()   // JSON string of all history
+---
+
+## Schema Validation
+
+`memorio.registerSchema(path, schema)` lets you register runtime validators for state paths. When a write to `state.somePath = value` violates a registered schema, the write is **rejected** before the value is stored.
+
+```typescript
+import 'memorio'
+
+memorio.registerSchema('user', {
+  type: 'object',
+  required: ['name', 'email'],
+  properties: {
+    name: { type: 'string', min: 1 },
+    email: { type: 'string', pattern: /^[^@]+@[^@]+$/ },
+    age: { type: 'number', min: 0, max: 150 }
+  }
+})
+
+state.user = { name: 'Sara', email: 'sara@test.com', age: 30 }  // accepted
+state.user = { name: 'Sara' }                                    // rejected: missing 'email'
+state.user = { name: 42 }                                        // rejected: wrong type
 ```
 
----
+Custom validator functions are also supported:
 
-## 🌍 Platform detection
+```typescript
+memorio.registerSchema('theme', (val) => {
+  return val === 'light' || val === 'dark'
+    ? true
+    : 'theme must be "light" or "dark"'
+})
 
-```javascript
-memorio.isBrowser()       // true in Chrome, Firefox, Safari
-memorio.isNode()          // true in Node.js
-memorio.isDeno()          // true in Deno
-memorio.isEdge()          // true in Cloudflare Workers, Vercel Edge
+state.theme = 'purple'  // rejected: "theme must be light or dark"
+state.theme = 'dark'    // accepted
+```
 
-const caps = memorio.getCapabilities()
-// { platform: 'browser', hasLocalStorage: true, hasIndexedDB: true, ... }
+Manual validation without writing:
+
+```typescript
+memorio.validate('user', { name: 'Sara', email: 'sara@test.com' })
+// { valid: true }
+
+memorio.validate('user', { name: 'Sara' })
+// { valid: false, errors: ["user: missing required property 'email'"] }
 ```
 
-Named exports work too:
+Manage registered schemas:
 
 ```typescript
-import { isBrowser, isNode, getCapabilities } from 'memorio'
+memorio.listSchemas()           // ['user', 'theme']
+memorio.unregisterSchema('theme')  // removes the validator
 ```
 
+**Typed + Schema** — combine both for full safety:
+
+```typescript
+interface AppState {
+  user: { name: string; email: string }
+  theme: 'light' | 'dark'
+}
+
+const app = memorio.typed<AppState>()
+
+memorio.registerSchema('user', {
+  type: 'object',
+  required: ['name', 'email'],
+  properties: {
+    name: { type: 'string', min: 1 },
+    email: { type: 'string', pattern: /^[^@]+@[^@]+$/ }
+  }
+})
+
+app.user = { names: 'Sara' }        // ❌ TS: wrong shape
+app.user = { name: '', email: '' }  // ❌ TS passes, ❌ runtime: name too short
+app.user = { name: 'Sara', email: 'sara@test.com' } // ✅ both pass
+```
+
+See [Schema Validation docs](markdown/SCHEMA.md) for the full schema definition reference.
+
 ---
 
-## 🏢 Context isolation (multi-tenant)
+## Memory System
 
-```javascript
-// Create isolated context
-const ctx = memorio.createContext('tenant-123')
+`memorio.memory` provides a semantic memory layer — a key/value store with **type safety**, **TTL**, **confidence scoring**, **tagging**, and **scope-based persistence**. It's designed for AI agents and applications that need structured, queryable memory with lifecycle management.
 
-// Use context storage (prefix: 'tenant-123-key')
-ctx.state.user = { name: 'Isolated' }
-ctx.store.set('settings', { theme: 'dark' })
-ctx.session.set('token', 'abc123')
+### Core API
 
-// Context is completely isolated from global state
-console.debug(state.user) // undefined
+```ts
+// remember(key, value, options)
+await memorio.memory.remember('user.language', 'Italian', {
+  type: 'preference',
+  confidence: 0.92,
+  scope: 'local',
+  ttl: null,           // never expires
+  tags: ['ui', 'user'],
+  source: 'conversation'
+})
 
-// Manage contexts
-memorio.listContexts()    // ['tenant-123']
-memorio.deleteContext('tenant-123')
+// recall(key, options)
+const lang = await memorio.memory.recall('user.language')
+// → 'Italian'
+
+// update(key, value, options) — creates a superseded version of the old entry
+await memorio.memory.update('user.language', 'English', { confidence: 0.95 })
+
+// forget(key) — permanently deletes
+await memorio.memory.forget('user.language')
 ```
 
-Named exports:
+### Scopes
 
-```typescript
-import { createContext, listContexts, deleteContext, isolate } from 'memorio'
+| Scope | Storage | TTL | Cross-session | Size limit |
+|---|---|---|---|---|
+| `hot` | `state` proxy | ✅ | ❌ | ~5MB (RAM) |
+| `session` | `sessionStorage` | ✅ | Tab only | ~5MB |
+| `local` | `localStorage` | ✅ | ✅ | ~10MB |
+| `durable` | `IndexedDB` | ✅ | ✅ | ~1GB+ |
+
+Default scope is `local` for values ≤100KB, `durable` for larger values.
+
+### Context API
+
+```ts
+// context() — returns ranked, relevant memories
+const context = await memorio.memory.context({
+  tags: 'user',
+  types: ['preference', 'decision'],
+  minConfidence: 0.7,
+  maxEntries: 10
+})
+// → [{ key, value, relevance, age, confidence, ... }]
+```
+
+### Memory Entry Model
+
+Each memory is stored as a structured entry:
+
+```ts
+{
+  id: string          // unique identifier
+  key: string         // path-like key (e.g. "user.preference.theme")
+  value: any          // the stored data
+  type: MemoryType    // 'fact' | 'preference' | 'decision' | 'task' | 'context'
+  confidence: number  // 0.0–1.0
+  scope: MemoryScope  // 'hot' | 'session' | 'local' | 'durable'
+  ttl?: number | null // milliseconds (null = never expires)
+  tags: string[]      // for filtering
+  source?: string     // where this memory came from
+  status: MemoryStatus // 'active' | 'obsolete' | 'superseded'
+  createdAt: number   // timestamp
+  lastConfirmedAt: number
+  supersededId?: string | null
+}
 ```
 
+### Memory Lifecycle
+
+| Operation | Behavior |
+|---|---|
+| `remember(key, newValue)` when entry exists | Old entry → `superseded` status, new entry → `active` |
+| `recall(key)` | Returns active value; expired entries return `null` unless `includeObsolete: true` |
+| `update(key, value)` | Creates superseded copy + updated active entry |
+| Entry with `ttl` expires | Status → `obsolete` (via `forgetExpired()`) |
+| `clear()` | Wipes all memories + index |
+
+See [Memory docs](markdown/MEMORY.md) for full reference.
+
 ---
 
-## 🖥️ Cross-Platform
+## Cross-Platform Behavior
 
-Memorio runs in every JavaScript environment, with automatic fallbacks.
+memorio runs everywhere JavaScript does - but "everywhere" means different guarantees in different places, and we'd rather tell you now than have you find out at 2am:
 
-| Tool | Browser | Node.js | Deno | Edge / Workers |
+| API | Browser | Node.js | Deno | Edge / Workers |
 |---|---|---|---|---|
-| `state` | ✅ | ✅ | ✅ | ✅ |
+| `state` | Proxy in memory | Proxy in memory | Proxy in memory | Proxy in memory |
 | `observer` / `useObserver` | ✅ | ✅ | ✅ | ✅ |
-| `cache` | ✅ | ✅ | ✅ | ✅ |
-| `store` | localStorage | memory | memory | localStorage |
-| `session` | sessionStorage | memory | memory | sessionStorage |
-| `idb` | IndexedDB | ❌ | ❌ | ⚠️ |
+| `cache` | ✅ in memory | ✅ in memory | ✅ in memory | ✅ in memory |
+| `store` | `localStorage` | `Map` fallback - **not durable across restarts** | `Map` fallback - not durable | `localStorage` where available, else `Map` |
+| `session` | `sessionStorage` | `Map` fallback - not durable | `Map` fallback - not durable | `sessionStorage` where available, else `Map` |
+| `idb` | ✅ `IndexedDB` | ❌ not available | ❌ not available | ⚠️ check `getCapabilities()` |
 | `devtools` | ✅ | ❌ | ❌ | ⚠️ |
 
-> **Why memory fallbacks on the server?** There is no browser. `store` and `session` gracefully fall back to `Map`. You still get the same API. Same `state`, same `cache`, same `useObserver`. No extra config required.
+Same API top to bottom - that's the promise. But if your server code leans on `store.get(...)` surviving a redeploy, know that on Node/Deno it won't; the fallback is an in-memory cache with the same shape, not durable storage.
+
+```javascript
+memorio.isBrowser()
+memorio.isNode()
+memorio.isDeno()
+memorio.isEdge()
+
+memorio.getCapabilities()
+// { platform: 'browser', hasLocalStorage: true, hasIndexedDB: true, ... }
+```
+
+Check `getCapabilities()` before leaning on `idb` or persistent `store`/`session` in code that might run on more than one platform.
 
 ---
 
-## 🔒 Security
+## Context Isolation (multi-tenant)
+
+```javascript
+const ctx = memorio.createContext('tenant-123')
+
+ctx.state.user = { name: 'Isolated' }
+ctx.store.set('settings', { theme: 'dark' })
+
+console.debug(state.user) // undefined - separate namespace
+```
+
+Handy for keeping per-tenant or per-request state from colliding in the same process. Under the hood it's a key prefix (`tenant-123-key`) inside the same storage - a naming convention, not a hard memory boundary. Great for a browser tab; if you're running this in a shared Node.js process or an edge isolate that might be reused across requests, make sure tenant IDs can't collide or be forged, and don't treat this as your only isolation layer if the stakes are real.
+
+---
+
+## Security
+
+- Zero production dependencies.
+- No `eval`, no dynamic code execution, no bundled telemetry.
+- Session IDs generated via `crypto.randomUUID`.
+- Inputs validated, keys sanitized, errors caught at module boundaries.
+
+memorio does **not** encrypt what you put into `store`, `session`, or `idb` - they're thin, fast wrappers over `localStorage`/`sessionStorage`/`IndexedDB`, which store data in the clear on the user's device. Bring your own encryption layer for tokens, secrets, or regulated personal data.
 
-- Zero production dependencies — no supply chain surprises
-- NIST & NSA aligned — enterprise-grade security standards
-- No `eval`, no obfuscation, no hardcoded secrets
-- All inputs validated, keys sanitized, errors caught
-- Secure random session IDs via `crypto.randomUUID`
+We build with recognized engineering guidance (NIST SP 800-53 practices) as an input to how we write code - that's a design discipline, not a compliance certificate, and no third-party audit has been performed. Found an issue? Report it privately - see `SECURITY.md` - rather than opening a public issue.
 
 ---
 
-## 📄 License
+## License
 
 MIT © [Dario Passariello](https://dario.passariello.ca)