From 9e30c6b6f8c33b531baa62aff28c6db46f65b19e Mon Sep 17 00:00:00 2001
From: "A. B. M. Mahmudul Hasan" <abmmhasan@users.noreply.github.com>
Date: Thu, 23 Apr 2026 16:34:43 +0600
Subject: [PATCH] updated docs

---
 README.md                      | 424 ++++-----------------------------
 docs/_static/theme.css         |   3 +
 docs/compatibility-matrix.md   |  27 ---
 docs/compatibility.rst         |  34 +++
 docs/conf.py                   |  60 +++++
 docs/db-storage.md             |  24 --
 docs/db-storage.rst            |  44 ++++
 docs/exceptions.rst            |  31 +++
 docs/framework-integration.md  |  21 --
 docs/framework-integration.rst |  40 ++++
 docs/helpers.rst               |  80 +++++++
 docs/id-facade.rst             |  66 +++++
 docs/index.rst                 |  47 ++++
 docs/installation.rst          |  41 ++++
 docs/quickstart.rst            |  73 ++++++
 docs/random-ids.rst            | 101 ++++++++
 docs/references.rst            |  19 ++
 docs/requirements.txt          |   7 +
 docs/sequence-providers.rst    |  83 +++++++
 docs/snowflake.rst             |  96 ++++++++
 docs/sonyflake.rst             |  84 +++++++
 docs/tbsl.rst                  |  76 ++++++
 docs/ulid.rst                  |  51 ++++
 docs/uuid.rst                  | 109 +++++++++
 docs/value-objects.rst         |  60 +++++
 25 files changed, 1250 insertions(+), 451 deletions(-)
 create mode 100644 docs/_static/theme.css
 delete mode 100644 docs/compatibility-matrix.md
 create mode 100644 docs/compatibility.rst
 create mode 100644 docs/conf.py
 delete mode 100644 docs/db-storage.md
 create mode 100644 docs/db-storage.rst
 create mode 100644 docs/exceptions.rst
 delete mode 100644 docs/framework-integration.md
 create mode 100644 docs/framework-integration.rst
 create mode 100644 docs/helpers.rst
 create mode 100644 docs/id-facade.rst
 create mode 100644 docs/index.rst
 create mode 100644 docs/installation.rst
 create mode 100644 docs/quickstart.rst
 create mode 100644 docs/random-ids.rst
 create mode 100644 docs/references.rst
 create mode 100644 docs/requirements.txt
 create mode 100644 docs/sequence-providers.rst
 create mode 100644 docs/snowflake.rst
 create mode 100644 docs/sonyflake.rst
 create mode 100644 docs/tbsl.rst
 create mode 100644 docs/ulid.rst
 create mode 100644 docs/uuid.rst
 create mode 100644 docs/value-objects.rst

diff --git a/README.md b/README.md
index 569320e..7b817e7 100644
--- a/README.md
+++ b/README.md
@@ -1,411 +1,77 @@
 # UID
 
-[![build](https://github.com/infocyph/UID/actions/workflows/build.yml/badge.svg?branch=main)](https://github.com/infocyph/UID/actions/workflows/build.yml)
-[![Codacy Badge](https://app.codacy.com/project/badge/Grade/cec4c7ed0e274b3da4571973732a363e)](https://app.codacy.com/gh/infocyph/UID/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
-![Packagist Downloads](https://img.shields.io/packagist/dt/infocyph/uid)
+[![Security & Standards](https://github.com/infocyph/UID/actions/workflows/build.yml/badge.svg)](https://github.com/infocyph/UID/actions/workflows/build.yml)
+[![Documentation](https://img.shields.io/badge/Documentation-UID-blue?logo=readthedocs&logoColor=white)](https://docs.infocyph.com/projects/UID/)
+![Packagist Downloads](https://img.shields.io/packagist/dt/infocyph/UID?color=green&link=https%3A%2F%2Fpackagist.org%2Fpackages%2Finfocyph%2FUID)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
-![Packagist Version](https://img.shields.io/packagist/v/infocyph/uid)
-![Packagist PHP Version Support](https://img.shields.io/packagist/php-v/infocyph/uid)
-![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/infocyph/uid)
-[![]()](https://visitor-badge.laobi.icu/badge?page_id=infocyph.com)
+![Packagist Version](https://img.shields.io/packagist/v/infocyph/UID)
+![Packagist PHP Version](https://img.shields.io/packagist/dependency-v/infocyph/UID/php)
+![GitHub Code Size](https://img.shields.io/github/languages/code-size/infocyph/UID)
 
-An AIO Unique ID generator written in PHP. Supports (references available at the bottom),
+All-in-one unique ID toolkit for PHP.
 
-- UUID
-- ULID
-- Snowflake ID
-- Sonyflake ID
-- TBSL
-- NanoId
-- Cuid2
+## Features
 
-## Table of contents
+- UUID (`v1`, `v3`, `v4`, `v5`, `v6`, `v7`, `v8`)
+- ULID (monotonic and random modes)
+- Snowflake, Sonyflake, TBSL
+- NanoID, CUID2, KSUID, XID
+- Opaque and deterministic IDs
+- Value objects and comparator utilities
+- Binary conversion and base encoders (`16`, `32`, `36`, `58`, `62`)
+- Pluggable sequence providers (filesystem, memory, PSR-16 cache, callback)
 
-<!--ts-->
+## Requirements
 
-* [Prerequisites](#prerequisites)
-* [Installation](#installation)
-* [Usage](#usage)
-    * [UUID](#uuid-universal-unique-identifier)
-        * [UUID v1](#uuid-v1-time-based-uuid)
-        * [UUID v3](#uuid-v3-namespace-based-uuid)
-        * [UUID v4](#uuid-v4-random-uuid)
-        * [UUID v5](#uuid-v5-namespace-based-uuid)
-        * [UUID v6](#uuid-v6-draft-basedunofficial-time-based-uuid)
-        * [UUID v7](#uuid-v7-draft-basedunofficial-time-based-uuid)
-        * [UUID v8](#uuid-v8-draft-basedunofficial-time-based-uuid-lexicographically-sortable)
-        * [GUID](#guid)
-        * [Additional](#additional)
-    * [ULID](#ulid-universally-unique-lexicographically-sortable-identifier)
-    * [Snowflake ID](#snowflake-id)
-    * [Sonyflake ID](#sonyflake-id)
-    * [TBSL ID](#tbsl-time-based-keys-with-lexicographic-sorting-library-exclusive)
-    * [RandomId](#randomid)
-        * [NanoId](#nanoid-url-friendly-unique-random-id)
-        * [Cuid2](#cuid2-url-friendly-secure--collision-free)
-* [Benchmark](#benchmark)
-* [Support](#support)
-* [References](#references)
-
-<!--te-->
-
-## Prerequisites
-
-Language: PHP 8.2+
+- PHP `>=8.2`
+- `ext-bcmath`
 
 ## Installation
 
-```
+```bash
 composer require infocyph/uid
 ```
 
-Global helper functions are available via Composer autoload.
-
-## Usage
-
-### UUID (Universal Unique Identifier)
-
-The node specific UUID's `$node` parameter (1, 6, 7, 8) is optional. If not provided, it will be generated randomly.
-But, if you wanna track the source of the UUIDs, you should use it (pre-define the node per server & pass it
-accordingly).
-
-#### UUID v1: Time-based UUID.
-
-- Generate v1 UUID
-
-```php
-// Get v1 UUID
-\Infocyph\UID\UUID::v1();
-// alternatively can also use
-uuid1();
-```
-
-- Pass your pre-generated node (for node specific UUID)
-
-```php
-\Infocyph\UID\UUID::v1($node); // check additional section for how to generate one
-```
-
-#### UUID v3: Namespace based UUID.
-
-- Generate v3 UUID
-
-```php
-// Get v3 UUID
-\Infocyph\UID\UUID::v3('a pre-generated UUID', 'the string you wanna get UUID for');
-// alternatively can also use
-uuid3();
-```
-
-- Get v3 UUID for predefined namespaces (RFC4122 #Appendix C)
-
-```php
-/**
-* You can pass X500, URL, OID, DNS (check RFC4122 #Appendix C)
-*/
-\Infocyph\UID\UUID::v3('url', 'abmmhasan.github.io');
-```
-
-- You can generate a UUID & use as namespace as well
-
-```php
-\Infocyph\UID\UUID::v3('fa1700dd-828c-4d1b-8e6d-a6104807da90', 'abmmhasan.github.io');
-```
-
-#### UUID v4: Random UUID.
-
-- Generate v4 UUID
-
-```php
-// Get v4 UUID (completely random)
-\Infocyph\UID\UUID::v4();
-// alternatively can also use
-uuid4();
-```
-
-#### UUID v5: Namespace based UUID.
-
-- Generate v5 UUID
-
-```php
-// Get v5 UUID
-\Infocyph\UID\UUID::v5('a pre-generated UUID', 'the string you wanna get UUID for');
-// alternatively can also use
-uuid5();
-```
-
-- Get v5 UUID for predefined namespaces (RFC4122 #Appendix C)
-
-```php
-/**
-* You can pass X500, URL, OID, DNS (check RFC4122 #Appendix C)
-*/
-\Infocyph\UID\UUID::v5('url', 'abmmhasan.github.io');
-```
-
-- You can generate a UUID & use as namespace as well
-
-```php
-UUID::v5('fa1700dd-828c-4d1b-8e6d-a6104807da90', 'abmmhasan.github.io');
-```
-
-#### UUID v6 (draft-based/unofficial): Time-based UUID.
-
-- Generate v6 UUID
-
-```php
-// Get v6 UUID (Time based)
-\Infocyph\UID\UUID::v6();
-// alternatively can also use
-uuid6();
-```
-
-- Get v6 UUID using predefined node:
-
-```php
-\Infocyph\UID\UUID::v6($node); // check additional section for how to generate one
-```
-
-#### UUID v7 (draft-based/unofficial): Time-based UUID.
-
-- Generate v7 UUID
-
-```php
-// Get v7 UUID for current time
-\Infocyph\UID\UUID::v7();
-// alternatively can also use
-uuid7();
-```
-
-- Get v7 UUID using predefined node:
-
-```php
-\Infocyph\UID\UUID::v7(null, $node); // check additional section for, how to generate one
-```
-
-- Or if you wanna get v7 UUID using predefined time:
-
-```php
-$timeInterface = new DateTime(); // DateTime implements DateTimeInterface
-\Infocyph\UID\UUID::v7($timeInterface);
-```
-
-- You can combine both parameters together as well.
-
-#### UUID v8 (draft-based/unofficial): Time-based UUID. Lexicographically sortable.
-
-- Generate v8 UUID
-
-```php
-// Get v8 UUID
-\Infocyph\UID\UUID::v8();
-// alternatively can also use
-uuid8();
-```
-
-- Get v8 UUID using predefined node:
-
-```php
-\Infocyph\UID\UUID::v8($node); // check additional section for, how to generate one
-```
-
-#### GUID
-
-GUID generator, works in all platform. Generate:
-
-```php
-\Infocyph\UID\UUID::guid()
-```
-
-_Note: Sending false in only parameter will return the string enclosed with Braces_
+Global helper functions are autoloaded via `src/functions.php`.
 
-#### Additional
-
-- Generate node for further use (with version: 1, 6, 7, 8)
+## Quick Usage
 
 ```php
-\Infocyph\UID\UUID::getNode();
-```
+<?php
 
-- Parse any UUID string:
+use Infocyph\UID\Id;
 
-```php
-\Infocyph\UID\UUID::parse($uuid); // returns ['isValid', 'version', 'variant', 'time', 'node', 'tail']
+$uuid = Id::uuid();      // default UUID strategy (v7)
+$ulid = Id::ulid();
+$snowflake = Id::snowflake();
+$sonyflake = Id::sonyflake();
+$tbsl = Id::tbsl();
+$nanoid = Id::nanoId(21);
+$cuid2 = Id::cuid2(24);
 ```
 
-
-### ULID (Universally Unique Lexicographically Sortable Identifier)
-
-- Generating ULID is very simple,
-
 ```php
-\Infocyph\UID\ULID::generate();
-```
+<?php
 
-- Or if you wanna get ULID for specific time:
+use Infocyph\UID\UUID;
 
-```php
-\Infocyph\UID\ULID::generate(new DateTimeImmutable('2020-01-01 00:00:00'));
-```
+$uuid = UUID::v7();
+$ok = UUID::isValid($uuid);
+$parsed = UUID::parse($uuid);
 
-- Extract datetime from any ULID string:
+$bytes = UUID::toBytes($uuid);
+$roundTrip = UUID::fromBytes($bytes);
 
-```php
-\Infocyph\UID\ULID::getTime($ulid); // returns DateTimeInterface object
+$base58 = UUID::toBase($uuid, 58);
+$decoded = UUID::fromBase($base58, 58);
 ```
 
-- Validate any ULID string:
-
-```php
-\Infocyph\UID\ULID::isValid($ulid); // true/false
-```
-
-### Snowflake ID
-
-- Generate a new Snowflake ID (You can also pass your pre-generated worker_id & datacenter_id for server/module
-  detection):
-
-```php
-// Get Snowflake ID
-// optionally you can set worker_id & datacenter_id, for server/module detection
-\Infocyph\UID\Snowflake::generate();
-// alternatively
-snowflake();
-```
-
-- Parse Snowflake ID (get the timestamp, sequence, worker_id, datacenter_id):
-
-```php
-// Parse Snowflake ID
-// returns [time => DateTimeInterface object, sequence, worker_id, datacenter_id]
-\Infocyph\UID\Snowflake::parse($snowflake);
-```
-
-- Specify start time for Snowflake ID (a Snowflake ID is unique upto 69 years from the start date):
-
-```php
-// By default, the start time is set to `2020-01-01 00:00:00`, which is changeable
-// but if changed, this should always stay same as long as your project lives
-// & must call this before any Snowflake call (generate/parse)
-\Infocyph\UID\Snowflake::setStartTimeStamp('2000-01-01 00:00:00');
-```
-
-### Sonyflake ID
-
-- Generate a new Sonyflake ID (You can also pass your pre-generated machine_id for server detection):
-
-```php
-// Get Sonyflake ID
-// optionally set machine_id, for server detection
-\Infocyph\UID\Sonyflake::generate();
-// alternatively
-\Infocyph\UID\sonyflake();
-```
-
-- Parse Sonyflake ID (get the timestamp, sequence, machine_id):
-
-```php
-// Parse Sonyflake ID
-// returns [time => DateTimeInterface object, sequence, machine_id]
-\Infocyph\UID\Sonyflake::parse($sonyflake);
-```
-
-- Specify start time for Sonyflake ID (a Sonyflake ID is unique upto 174 years from the start date):
-
-```php
-// By default, the start time is set to `2020-01-01 00:00:00`, which is changeable
-// but if changed, this should always stay same as long as your project lives
-// & must call this before any Sonyflake call (generate/parse)
-\Infocyph\UID\Sonyflake::setStartTimeStamp('2000-01-01 00:00:00');
-```
-
-### TBSL: Time-Based Keys with Lexicographic Sorting (library exclusive)
-
-- Get TBSL ID (You can also pass your pre-generated machine_id for server detection):
-
-```php
-// Get TBSL ID
-// optionally set machine_id, for server detection
-\Infocyph\UID\TBSL::generate();
-// alternatively
-tbsl();
-```
-
-- Parse TBSL ID (get the timestamp, machine_id):
-
-```php
-// Parse TBSL
-// returns [isValid, time => DateTimeInterface object, machine_id]
-\Infocyph\UID\TBSL::parse($tbsl);
-```
-- Getting unique sequence
-
-```php
-tbsl(0, true); // send true in 2nd parameter to enable sequence
-```
-
-### RandomId
-
-With this you can generate RandomIds. These are great for usage where you don't want a large length/formatted IDs like UUID4. 
-These IDs are unique & can't be backtracked.
-
-#### NanoID (URL friendly Unique Random ID)
-
-- Generate
-
-```php
-// By default, it will generate id of length 21.
-// You can pass in desired length
-\Infocyph\UID\RandomId::nanoId();
-```
-
-#### Cuid2 (URL friendly, secure & collision free)
-
-- Generate
-
-```php
-// By default, it will generate id of length 24.
-// You can pass in desired length in between 4 & 32
-\Infocyph\UID\RandomId::cuid2();
-```
-
-## Benchmark
-
-Additional hotspot benchmarks (same-ms bursts, parser speed, and provider overhead) are available in [`benchmarks/`](benchmarks/).
-
-| Type                       |                               Generation time (ms)                                |
-|:---------------------------|:---------------------------------------------------------------------------------:|
-| UUID v1 (random node)      |                          0.00411 (ramsey/Uuid: 0.18753)                           |
-| UUID v1 (fixed node)       |                          0.00115 (ramsey/Uuid: 0.17386)                           |         
-| UUID v3 (custom namespace) |                          0.00257 (ramsey/Uuid: 0.03015)                           |         
-| UUID v4                    |                          0.00362 (ramsey/Uuid: 0.16501)                           |         
-| UUID v5 (custom namespace) |                          0.00108 (ramsey/Uuid: 0.03658)                           |       
-| UUID v6 (random node)      |                          0.00444 (ramsey/Uuid: 0.17469)                           |     
-| UUID v6 (fixed node)       |                          0.00164 (ramsey/Uuid: 0.17382)                           |     
-| UUID v7 (random node)      |                          0.00503 (ramsey/Uuid: 0.16278)                           |    
-| UUID v7 (fixed node)       |                          0.00154 (ramsey/Uuid: 0.18753)                           |   
-| UUID v8 (random node)      |                            0.00505 (ramsey/Uuid: N/A)                             |  
-| UUID v8 (fixed node)       | 0.00209 (ramsey/Uuid: 0.16029 _*predefined random node, not usable as signature_) |              
-| ULID                       |                    0.00506 (robinvdvleuten/php-ulid: 0.00508)                     |           
-| Snowflake                  |                     0.13951 (godruoyi/php-snowflake: 0.14856)                     |            
-| Sonyflake                  |                     0.13821 (godruoyi/php-snowflake: 0.14583)                     |             
-| TBSL                       |                                      0.0034                                       | 
-| NanoID                     |                                      0.00057                                      | 
-| Cuid2                      |                                      0.01817                                      | 
-
-## Support
-
-Having trouble? Create an issue!
-
 ## References
 
-- UUID (RFC4122/RFC9562): https://datatracker.ietf.org/doc/html/rfc9562
+- UUID: https://datatracker.ietf.org/doc/html/rfc9562
 - ULID: https://github.com/ulid/spec
-- Snowflake ID: https://github.com/twitter-archive/snowflake/tree/snowflake-2010
-- Sonyflake ID: https://github.com/sony/sonyflake
-- TBSL ID: https://github.com/infocyph/UID/blob/main/TBSL.md
+- Snowflake: https://github.com/twitter-archive/snowflake/tree/snowflake-2010
+- Sonyflake: https://github.com/sony/sonyflake
 - NanoID: https://github.com/ai/nanoid
-- Cuid2: https://github.com/paralleldrive/cuid2
-- Compatibility matrix: [docs/compatibility-matrix.md](docs/compatibility-matrix.md)
-- DB storage notes: [docs/db-storage.md](docs/db-storage.md)
-- Framework integration notes: [docs/framework-integration.md](docs/framework-integration.md)
+- CUID2: https://github.com/paralleldrive/cuid2
+- TBSL note: https://github.com/infocyph/UID/blob/main/TBSL.md
diff --git a/docs/_static/theme.css b/docs/_static/theme.css
new file mode 100644
index 0000000..ae81ea7
--- /dev/null
+++ b/docs/_static/theme.css
@@ -0,0 +1,3 @@
+.highlight-php .k {
+  color: #0077aa; /* Example: make PHP keywords a different color */
+}
diff --git a/docs/compatibility-matrix.md b/docs/compatibility-matrix.md
deleted file mode 100644
index 21ab268..0000000
--- a/docs/compatibility-matrix.md
+++ /dev/null
@@ -1,27 +0,0 @@
-# Compatibility Matrix
-
-## UUID support
-
-- `v1`, `v3`, `v4`, `v5`: RFC 4122 / RFC 9562 compatible layouts.
-- `v6`, `v7`: RFC 9562 time-ordered UUIDs.
-- `v8`: custom payload strategy inside RFC 9562 v8 envelope.
-- `guid()`: Microsoft-compatible GUID text formatting helper.
-
-## Non-UUID families
-
-- `ULID`: Crockford base32 ULID (monotonic + random generation modes).
-- `Snowflake`: 64-bit Twitter-style ID (41/5/5/12 layout).
-- `Sonyflake`: 64-bit Sonyflake-style ID (39/16/8 layout).
-- `TBSL`: project-specific time-based sortable hex identifier.
-- `NanoID`, `CUID2`: random ID families for URL-safe usage.
-
-## Binary and alternate representations
-
-- UUID / ULID / TBSL: `toBytes()` / `fromBytes()`.
-- UUID / ULID / TBSL / Snowflake / Sonyflake: base encodings via `toBase()` / `fromBase()` where applicable.
-
-## Runtime
-
-- Minimum PHP: `8.2`.
-- Required extension: `ext-bcmath`.
-- Optional sequence backends: filesystem (default), in-memory, PSR-16 simple cache, callback.
diff --git a/docs/compatibility.rst b/docs/compatibility.rst
new file mode 100644
index 0000000..e206b3c
--- /dev/null
+++ b/docs/compatibility.rst
@@ -0,0 +1,34 @@
+Compatibility Matrix
+====================
+
+UUID Support
+------------
+
+- ``v1``, ``v3``, ``v4``, ``v5``: RFC 4122 / RFC 9562 compatible layouts.
+- ``v6``, ``v7``: RFC 9562 time-ordered UUIDs.
+- ``v8``: custom payload strategy inside UUID v8 envelope.
+- ``guid()``: Microsoft-compatible GUID text formatting helper.
+
+Non-UUID Families
+-----------------
+
+- ULID: Crockford Base32 ULID with monotonic and random modes.
+- Snowflake: 64-bit Twitter-style ID (41/5/5/12).
+- Sonyflake: 64-bit Sonyflake-style ID (39/16/8).
+- TBSL: project-specific time-based sortable hex identifier.
+- NanoID and CUID2: URL-safe random IDs.
+- KSUID and XID: sortable short ID families.
+
+Binary and Alternate Encodings
+------------------------------
+
+- UUID / ULID / TBSL: ``toBytes()`` / ``fromBytes()``.
+- UUID / ULID / Snowflake / Sonyflake / TBSL: ``toBase()`` / ``fromBase()``.
+- KSUID / XID: ``toBytes()`` / ``fromBytes()``.
+
+Runtime Requirements
+--------------------
+
+- Minimum PHP: ``8.2``
+- Required extension: ``ext-bcmath``
+- Optional sequence backends: filesystem, in-memory, PSR-16 cache, callback.
diff --git a/docs/conf.py b/docs/conf.py
new file mode 100644
index 0000000..878090b
--- /dev/null
+++ b/docs/conf.py
@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import datetime
+import os
+
+project = "UID"
+author = "Infocyph"
+year_now = datetime.date.today().strftime("%Y")
+copyright = f"2024-{year_now}"
+version = os.environ.get("READTHEDOCS_VERSION", "latest")
+release = version
+language = "en"
+root_doc = "index"
+
+extensions = [
+    "myst_parser",
+    "sphinx.ext.todo",
+    "sphinx.ext.autosectionlabel",
+    "sphinx.ext.intersphinx",
+    "sphinx_copybutton",
+    "sphinx_design",
+    "sphinxcontrib.phpdomain",
+]
+
+myst_enable_extensions = [
+    "colon_fence",
+    "deflist",
+    "attrs_block",
+    "attrs_inline",
+    "tasklist",
+    "fieldlist",
+]
+
+myst_heading_anchors = 3
+autosectionlabel_prefix_document = True
+todo_include_todos = True
+
+intersphinx_mapping = {
+    "php": ("https://www.php.net/manual/en/", None),
+}
+
+html_theme = "sphinx_book_theme"
+html_theme_options = {
+    "repository_url": "https://github.com/infocyph/UID",
+    "repository_branch": "main",
+    "path_to_docs": "docs",
+    "use_repository_button": True,
+    "use_issues_button": True,
+    "use_download_button": True,
+    "home_page_in_toc": True,
+    "show_toc_level": 2,
+}
+
+templates_path = ["_templates"]
+html_static_path = ["_static"]
+html_css_files = ["theme.css"]
+html_title = f"UID - {version} Documentation"
+html_show_sourcelink = True
+html_show_sphinx = False
+html_last_updated_fmt = "%Y-%m-%d"
diff --git a/docs/db-storage.md b/docs/db-storage.md
deleted file mode 100644
index 789d5c5..0000000
--- a/docs/db-storage.md
+++ /dev/null
@@ -1,24 +0,0 @@
-# Sortable DB Helpers
-
-## UUID
-
-- MySQL: prefer `BINARY(16)` for compact indexes.
-- PostgreSQL: prefer native `UUID` type.
-- Ordering: use UUIDv7 when insertion locality matters.
-
-## ULID
-
-- MySQL: `CHAR(26)` (human-friendly) or `BINARY(16)` (compact).
-- PostgreSQL: `CHAR(26)` or `BYTEA`.
-- Ordering: canonical ULID text preserves chronological order.
-
-## Snowflake / Sonyflake
-
-- MySQL: `BIGINT UNSIGNED`.
-- PostgreSQL: `BIGINT` if in range, otherwise `NUMERIC(20,0)`.
-- Ordering: numeric sort is time sort.
-
-## TBSL
-
-- Store as fixed-length uppercase hex: `CHAR(20)`.
-- If compactness matters, store bytes in `BINARY(10)` via `toBytes()`.
diff --git a/docs/db-storage.rst b/docs/db-storage.rst
new file mode 100644
index 0000000..e5b2ebd
--- /dev/null
+++ b/docs/db-storage.rst
@@ -0,0 +1,44 @@
+Database Storage
+================
+
+UID includes ``Infocyph\\UID\\DbStorage`` with recommendations for UUID, ULID, and Snowflake.
+
+UUID
+----
+
+- MySQL: prefer ``BINARY(16)`` for compact indexes.
+- PostgreSQL: prefer native ``UUID`` type.
+- Ordering: ``UUIDv7`` provides better insertion locality than ``UUIDv4``.
+
+ULID
+----
+
+- MySQL: ``CHAR(26)`` (readable) or ``BINARY(16)`` (compact/index-friendly).
+- PostgreSQL: ``CHAR(26)`` or ``BYTEA`` depending on interoperability.
+- Ordering: canonical ULID text is chronologically sortable.
+
+Snowflake and Sonyflake
+-----------------------
+
+- MySQL: ``BIGINT UNSIGNED``.
+- PostgreSQL: ``BIGINT`` if range is safe, otherwise ``NUMERIC(20,0)``.
+- Ordering: numeric sort equals time sort.
+
+TBSL
+----
+
+- Use ``CHAR(20)`` for canonical uppercase hex.
+- Use ``BINARY(10)`` when compactness matters.
+
+Programmatic Access
+-------------------
+
+.. code-block:: php
+
+   <?php
+
+   use Infocyph\UID\DbStorage;
+
+   $uuidAdvice = DbStorage::uuid();
+   $ulidAdvice = DbStorage::ulid();
+   $snowflakeAdvice = DbStorage::snowflake();
diff --git a/docs/exceptions.rst b/docs/exceptions.rst
new file mode 100644
index 0000000..96bb7bb
--- /dev/null
+++ b/docs/exceptions.rst
@@ -0,0 +1,31 @@
+Exceptions
+==========
+
+Hierarchy
+---------
+
+- ``Infocyph\\UID\\Exceptions\\UIDException``
+- ``Infocyph\\UID\\Exceptions\\UUIDException``
+- ``Infocyph\\UID\\Exceptions\\ULIDException``
+- ``Infocyph\\UID\\Exceptions\\SnowflakeException``
+- ``Infocyph\\UID\\Exceptions\\SonyflakeException``
+- ``Infocyph\\UID\\Exceptions\\FileLockException``
+
+Usage Pattern
+-------------
+
+Catch specific exceptions when you need algorithm-level handling,
+or catch ``UIDException`` for a package-wide fallback.
+
+.. code-block:: php
+
+   <?php
+
+   use Infocyph\UID\Exceptions\UIDException;
+   use Infocyph\UID\UUID;
+
+   try {
+       $uuid = UUID::normalize('{INVALID}');
+   } catch (UIDException $e) {
+       // Handle UID package errors.
+   }
diff --git a/docs/framework-integration.md b/docs/framework-integration.md
deleted file mode 100644
index 75c9060..0000000
--- a/docs/framework-integration.md
+++ /dev/null
@@ -1,21 +0,0 @@
-# Framework Integration Notes
-
-## Laravel
-
-- Helper functions are available automatically via Composer autoload.
-
-- Prefer UUIDv7 / ULID for ordered primary keys.
-- Keep IDs as strings at app boundary; convert to binary for DB only when needed.
-
-## Symfony
-
-- Helper functions are available automatically via Composer autoload.
-
-- Use `Id` factory in services to centralize generation strategy.
-
-## Generic PHP apps
-
-- Use `Id::nanoId()` for URL-safe public IDs.
-- Use configuration objects (`SnowflakeConfig`, `SonyflakeConfig`, `TBSLConfig`) for policy/output tuning.
-- Use value objects (`UuidValue`, `UlidValue`, etc.) for safer domain modeling.
-- For distributed sequence coordination with PSR-16 caches, pass a shared synchronizer callback to `PsrSimpleCacheSequenceProvider`.
diff --git a/docs/framework-integration.rst b/docs/framework-integration.rst
new file mode 100644
index 0000000..4cd2772
--- /dev/null
+++ b/docs/framework-integration.rst
@@ -0,0 +1,40 @@
+Framework Integration
+=====================
+
+Laravel
+-------
+
+- Helper functions are available through Composer autoload.
+- Prefer UUIDv7 or ULID for ordered primary keys.
+- Keep IDs as strings in application boundaries; convert to binary only at persistence edges.
+
+Symfony
+-------
+
+- Helper functions are available through Composer autoload.
+- Prefer central generation through ``Infocyph\\UID\\Id`` inside services.
+
+Generic PHP Apps
+----------------
+
+- Use ``Id::nanoId()`` for short public IDs.
+- Use ``Id::deterministic()`` for stable IDs from payloads.
+- Use config objects for policy/output tuning:
+
+  - ``SnowflakeConfig``
+  - ``SonyflakeConfig``
+  - ``TBSLConfig``
+
+- Use value objects for richer domain models:
+
+  - ``UuidValue``
+  - ``UlidValue``
+  - ``SnowflakeValue``
+  - ``SonyflakeValue``
+  - ``TbslValue``
+
+Distributed Sequence Coordination
+---------------------------------
+
+For PSR-16 cache providers in distributed environments, use
+``PsrSimpleCacheSequenceProvider`` with a synchronizer callback backed by a distributed lock.
diff --git a/docs/helpers.rst b/docs/helpers.rst
new file mode 100644
index 0000000..82dc413
--- /dev/null
+++ b/docs/helpers.rst
@@ -0,0 +1,80 @@
+Global Helper Functions
+=======================
+
+UID autoloads helper functions from ``src/functions.php``.
+
+UUID Helpers
+------------
+
+- ``uuid1(?string $node = null)``
+- ``uuid3(string $namespace, string $string)``
+- ``uuid4()``
+- ``uuid5(string $namespace, string $string)``
+- ``uuid6(?string $node = null)``
+- ``uuid7(?DateTimeInterface $dateTime = null, ?string $node = null)``
+- ``uuid8(?string $node = null)``
+- ``guid(bool $trim = true)``
+
+UUID Utility Helpers
+--------------------
+
+- ``uuid_nil()``, ``uuid_max()``
+- ``uuid_is_nil(string $uuid)``, ``uuid_is_max(string $uuid)``
+- ``uuid_normalize(string $uuid)``, ``uuid_compact(string $uuid)``
+- ``uuid_urn(string $uuid)``, ``uuid_braces(string $uuid)``
+- ``uuid_to_base(string $uuid, int $base)``, ``uuid_from_base(string $encoded, int $base)``
+
+ULID Helpers
+------------
+
+- ``ulid(?DateTimeInterface $dateTime = null)``
+- ``ulid_monotonic(?DateTimeInterface $dateTime = null)``
+- ``ulid_random(?DateTimeInterface $dateTime = null)``
+- ``ulid_to_base(string $ulid, int $base)``
+- ``ulid_from_base(string $encoded, int $base)``
+
+Snowflake/Sonyflake/TBSL Helpers
+--------------------------------
+
+- ``snowflake(int $datacenter = 0, int $workerId = 0)``
+- ``snowflake_is_valid(string $id)``
+- ``snowflake_to_base(string $id, int $base)``
+- ``snowflake_from_base(string $encoded, int $base)``
+
+- ``sonyflake(int $machineId = 0)``
+- ``sonyflake_is_valid(string $id)``
+- ``sonyflake_to_base(string $id, int $base)``
+- ``sonyflake_from_base(string $encoded, int $base)``
+
+- ``tbsl(int $machineId = 0, bool $sequenced = false)``
+- ``tbsl_is_valid(string $id)``
+- ``tbsl_to_base(string $id, int $base)``
+- ``tbsl_from_base(string $encoded, int $base)``
+
+Short/Random/Opaque Helpers
+---------------------------
+
+- ``nanoid(int $size = 21)``
+- ``nanoid_is_valid(string $id, ?int $size = null)``
+- ``cuid2(int $maxLength = 24)``
+- ``cuid2_is_valid(string $id)``
+- ``opaque_id(int $length = 12)``
+- ``deterministic_id(string $payload, int $length = 24, string $namespace = 'default')``
+
+Other Helpers
+-------------
+
+- ``ksuid(?DateTimeInterface $dateTime = null)``
+- ``xid()``
+
+Example
+-------
+
+.. code-block:: php
+
+   <?php
+
+   $id = uuid7();
+   $ul = ulid_random();
+   $sf = snowflake(1, 2);
+   $short = nanoid(16);
diff --git a/docs/id-facade.rst b/docs/id-facade.rst
new file mode 100644
index 0000000..9575fb8
--- /dev/null
+++ b/docs/id-facade.rst
@@ -0,0 +1,66 @@
+Id Facade
+=========
+
+The ``Infocyph\\UID\\Id`` class is the unified entry point for all generators and helpers.
+
+Default Strategy
+----------------
+
+``Id::uuid()`` maps to ``UUID::v7()`` by default.
+
+Core Generation Methods
+-----------------------
+
+- ``Id::uuid1()``, ``Id::uuid3()``, ``Id::uuid4()``, ``Id::uuid5()``, ``Id::uuid6()``, ``Id::uuid7()``, ``Id::uuid8()``
+- ``Id::ulid()``
+- ``Id::snowflake()``
+- ``Id::sonyflake()``
+- ``Id::tbsl()``
+- ``Id::nanoId()``
+- ``Id::cuid2()``
+- ``Id::ksuid()``
+- ``Id::xid()``
+- ``Id::opaque()``
+- ``Id::deterministic()``
+
+Value Object Helpers
+--------------------
+
+The facade also exposes value-object constructors:
+
+- ``Id::uuid1Value()``, ``Id::uuid3Value()``, ..., ``Id::uuid8Value()``
+- ``Id::uuidValue($uuid)``
+- ``Id::ulidValue()``
+- ``Id::snowflakeValue()``
+- ``Id::sonyflakeValue()``
+- ``Id::tbslValue()``
+
+UUID Utility Helpers via Id
+---------------------------
+
+- ``uuidNil()``, ``uuidMax()``, ``uuidIsNil()``, ``uuidIsMax()``, ``uuidIsValid()``
+- ``uuidNormalize()``, ``uuidCompact()``, ``uuidBraces()``, ``uuidUrn()``
+- ``uuidToBytes()``, ``uuidFromBytes()``
+- ``uuidToBase()``, ``uuidFromBase()``
+- ``uuidParse()``
+
+NanoID/CUID2 Utility Helpers via Id
+-----------------------------------
+
+- ``nanoIdIsValid()``, ``nanoIdParse()``
+- ``cuid2IsValid()``, ``cuid2Parse()``
+
+Example
+-------
+
+.. code-block:: php
+
+   <?php
+
+   use Infocyph\UID\Id;
+
+   $uuidV7 = Id::uuid();
+   $uuidV4 = Id::uuid4();
+
+   $uuidValue = Id::uuidValue($uuidV7);
+   $isSortable = $uuidValue->isSortable();
diff --git a/docs/index.rst b/docs/index.rst
new file mode 100644
index 0000000..989fee3
--- /dev/null
+++ b/docs/index.rst
@@ -0,0 +1,47 @@
+UID Documentation
+=================
+
+UID is an all-in-one ID toolkit for PHP with generation, parsing, validation, and conversion APIs.
+
+It supports:
+
+- UUID (v1, v3, v4, v5, v6, v7, v8)
+- ULID
+- Snowflake
+- Sonyflake
+- TBSL
+- NanoID and CUID2
+- KSUID and XID
+- Opaque and deterministic IDs
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Getting Started
+
+   installation
+   quickstart
+   id-facade
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Generators
+
+   uuid
+   ulid
+   snowflake
+   sonyflake
+   tbsl
+   random-ids
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Advanced
+
+   sequence-providers
+   value-objects
+   helpers
+   db-storage
+   compatibility
+   framework-integration
+   exceptions
+   references
diff --git a/docs/installation.rst b/docs/installation.rst
new file mode 100644
index 0000000..8575c2f
--- /dev/null
+++ b/docs/installation.rst
@@ -0,0 +1,41 @@
+Installation
+============
+
+Requirements
+------------
+
+- PHP ``>=8.2``
+- ``ext-bcmath``
+- Composer
+
+Install
+-------
+
+.. code-block:: bash
+
+   composer require infocyph/uid
+
+Autoloaded Helpers
+------------------
+
+UID ships global helper functions via Composer autoload from ``src/functions.php``.
+
+If you prefer explicit static APIs only, call the namespaced classes directly:
+
+- ``Infocyph\\UID\\Id``
+- ``Infocyph\\UID\\UUID``
+- ``Infocyph\\UID\\ULID``
+- ``Infocyph\\UID\\Snowflake``
+- ``Infocyph\\UID\\Sonyflake``
+- ``Infocyph\\UID\\TBSL``
+
+Read the Docs Build
+-------------------
+
+This repository already includes:
+
+- ``docs/conf.py``
+- ``docs/requirements.txt``
+- ``.readthedocs.yaml``
+
+So you can publish directly on Read the Docs without extra Sphinx bootstrapping.
diff --git a/docs/quickstart.rst b/docs/quickstart.rst
new file mode 100644
index 0000000..9fe18c9
--- /dev/null
+++ b/docs/quickstart.rst
@@ -0,0 +1,73 @@
+Quickstart
+==========
+
+Using the ``Id`` Facade
+-----------------------
+
+.. code-block:: php
+
+   <?php
+
+   use Infocyph\UID\Id;
+
+   $uuid = Id::uuid();          // default UUID strategy (v7)
+   $ulid = Id::ulid();
+   $snowflake = Id::snowflake();
+   $sonyflake = Id::sonyflake();
+   $tbsl = Id::tbsl();
+   $nano = Id::nanoId(21);
+   $cuid2 = Id::cuid2(24);
+
+Validation and Parsing
+----------------------
+
+.. code-block:: php
+
+   <?php
+
+   use Infocyph\UID\Id;
+
+   Id::uuidIsValid($uuid);          // bool
+   Id::uuidParse($uuid);            // ['isValid', 'version', 'variant', 'time', 'node', 'tail']
+
+   Id::nanoIdIsValid($nano, 21);    // bool
+   Id::nanoIdParse($nano, 21);      // ['isValid', 'length', 'alphabet']
+
+   Id::cuid2IsValid($cuid2);        // bool
+   Id::cuid2Parse($cuid2);          // ['isValid', 'length']
+
+Binary and Base Conversion
+--------------------------
+
+.. code-block:: php
+
+   <?php
+
+   use Infocyph\UID\Id;
+
+   $bytes = Id::uuidToBytes($uuid);       // 16 bytes
+   $roundTrip = Id::uuidFromBytes($bytes);
+
+   $base58 = Id::uuidToBase($uuid, 58);
+   $uuidAgain = Id::uuidFromBase($base58, 58);
+
+Configuration-Based Generators
+------------------------------
+
+.. code-block:: php
+
+   <?php
+
+   use Infocyph\UID\Configuration\SnowflakeConfig;
+   use Infocyph\UID\Enums\ClockBackwardPolicy;
+   use Infocyph\UID\Enums\IdOutputType;
+   use Infocyph\UID\Id;
+
+   $config = new SnowflakeConfig(
+       datacenterId: 1,
+       workerId: 7,
+       clockBackwardPolicy: ClockBackwardPolicy::WAIT,
+       outputType: IdOutputType::STRING,
+   );
+
+   $id = Id::snowflake($config);
diff --git a/docs/random-ids.rst b/docs/random-ids.rst
new file mode 100644
index 0000000..6bbc072
--- /dev/null
+++ b/docs/random-ids.rst
@@ -0,0 +1,101 @@
+Random and Short IDs
+====================
+
+NanoID and CUID2
+----------------
+
+Class: ``Infocyph\\UID\\RandomId``
+
+.. code-block:: php
+
+   <?php
+
+   use Infocyph\UID\RandomId;
+
+   $nano = RandomId::nanoId(21);
+   $isNano = RandomId::isNanoId($nano, 21);
+   $nanoInfo = RandomId::parseNanoId($nano, 21);
+
+   $cuid2 = RandomId::cuid2(24);
+   $isCuid2 = RandomId::isCuid2($cuid2);
+   $cuid2Info = RandomId::parseCuid2($cuid2);
+
+Validation/parsing outputs:
+
+- ``parseNanoId()``: ``['isValid', 'length', 'alphabet']``
+- ``parseCuid2()``: ``['isValid', 'length']``
+
+KSUID
+-----
+
+Class: ``Infocyph\\UID\\KSUID``
+
+- fixed-length 27-char Base62 string
+- sortable by timestamp prefix
+
+.. code-block:: php
+
+   <?php
+
+   use Infocyph\UID\KSUID;
+
+   $id = KSUID::generate();
+   $ok = KSUID::isValid($id);
+   $parts = KSUID::parse($id);  // ['isValid', 'time', 'payload']
+
+   $bytes = KSUID::toBytes($id);
+   $same = KSUID::fromBytes($bytes);
+
+XID
+---
+
+Class: ``Infocyph\\UID\\XID``
+
+- fixed-length 20-char Base32 lowercase string
+- includes timestamp, machine, pid, counter
+
+.. code-block:: php
+
+   <?php
+
+   use Infocyph\UID\XID;
+
+   $id = XID::generate();
+   $ok = XID::isValid($id);
+   $parts = XID::parse($id);  // ['isValid', 'time', 'machine', 'pid', 'counter']
+
+   $bytes = XID::toBytes($id);
+   $same = XID::fromBytes($bytes);
+
+Opaque IDs
+----------
+
+Class: ``Infocyph\\UID\\OpaqueId``
+
+- ``OpaqueId::random($length)`` for short public IDs
+- ``OpaqueId::fromInt($value, $salt)`` and ``OpaqueId::toInt($token, $salt)`` for reversible obfuscation
+
+.. code-block:: php
+
+   <?php
+
+   use Infocyph\UID\OpaqueId;
+
+   $token = OpaqueId::fromInt(123456, 'app-secret-salt');
+   $value = OpaqueId::toInt($token, 'app-secret-salt');
+
+Deterministic IDs
+-----------------
+
+Class: ``Infocyph\\UID\\DeterministicId``
+
+``DeterministicId::fromPayload($payload, $length = 24, $namespace = 'default')``
+creates deterministic Base62 output from payload + namespace.
+
+.. code-block:: php
+
+   <?php
+
+   use Infocyph\UID\DeterministicId;
+
+   $id = DeterministicId::fromPayload('user:42', 24, 'users');
diff --git a/docs/references.rst b/docs/references.rst
new file mode 100644
index 0000000..7d3fb67
--- /dev/null
+++ b/docs/references.rst
@@ -0,0 +1,19 @@
+References
+==========
+
+Standards and Specs
+-------------------
+
+- UUID RFC 9562: https://datatracker.ietf.org/doc/html/rfc9562
+- ULID spec: https://github.com/ulid/spec
+- Twitter Snowflake (archived): https://github.com/twitter-archive/snowflake/tree/snowflake-2010
+- Sonyflake: https://github.com/sony/sonyflake
+- NanoID: https://github.com/ai/nanoid
+- CUID2: https://github.com/paralleldrive/cuid2
+
+Project-Specific
+----------------
+
+- TBSL design note: https://github.com/infocyph/UID/blob/main/TBSL.md
+- Package source: https://github.com/infocyph/UID
+- Packagist: https://packagist.org/packages/infocyph/uid
diff --git a/docs/requirements.txt b/docs/requirements.txt
new file mode 100644
index 0000000..cddeba8
--- /dev/null
+++ b/docs/requirements.txt
@@ -0,0 +1,7 @@
+sphinx>=8.0,<9
+myst-parser>=2.0
+sphinx-book-theme>=1.1
+sphinxcontrib-phpdomain>=0.9
+sphinx-copybutton>=0.5.2
+sphinx-design>=0.6
+linkify-it-py>=2.0
diff --git a/docs/sequence-providers.rst b/docs/sequence-providers.rst
new file mode 100644
index 0000000..c8d8f52
--- /dev/null
+++ b/docs/sequence-providers.rst
@@ -0,0 +1,83 @@
+Sequence Providers
+==================
+
+UID supports pluggable sequence backends for Snowflake, Sonyflake, and sequenced TBSL.
+
+Supported Providers
+-------------------
+
+- ``FilesystemSequenceProvider`` (default)
+- ``InMemorySequenceProvider``
+- ``PsrSimpleCacheSequenceProvider``
+- ``CallbackSequenceProvider``
+- Any custom ``SequenceProviderInterface`` implementation
+
+Per-Algorithm Static Selection
+------------------------------
+
+Each algorithm class using ``GetSequence`` provides these static methods:
+
+- ``setSequenceProvider(SequenceProviderInterface $provider)``
+- ``resetSequenceProvider()``
+- ``useFilesystemSequenceProvider(?string $baseDirectory = null, int $waitTime = 100, int $maxAttempts = 10)``
+- ``useInMemorySequenceProvider()``
+- ``useSimpleCacheSequenceProvider(CacheInterface $cache, string $prefix = 'uid:seq:', int $waitTime = 100, int $maxAttempts = 10)``
+- ``useSequenceCallback(callable $callback)``
+
+Example: Process-Local In-Memory
+--------------------------------
+
+.. code-block:: php
+
+   <?php
+
+   use Infocyph\UID\Snowflake;
+
+   Snowflake::useInMemorySequenceProvider();
+   $id = Snowflake::generate(1, 1);
+
+Example: PSR-16 Simple Cache
+----------------------------
+
+.. code-block:: php
+
+   <?php
+
+   use Infocyph\UID\Sequence\PsrSimpleCacheSequenceProvider;
+   use Infocyph\UID\Snowflake;
+   use Psr\SimpleCache\CacheInterface;
+
+   /** @var CacheInterface $cache */
+   $provider = new PsrSimpleCacheSequenceProvider($cache, 'uid:seq:');
+   Snowflake::setSequenceProvider($provider);
+
+Example: External Synchronizer
+------------------------------
+
+``PsrSimpleCacheSequenceProvider`` optionally accepts a synchronizer callback:
+
+.. code-block:: php
+
+   <?php
+
+   $provider = new PsrSimpleCacheSequenceProvider(
+       cache: $cache,
+       synchronizer: function (string $key, callable $criticalSection): mixed {
+           // Acquire distributed lock here (Redis, DB, etc.)
+           // then run and return the critical section result.
+           return $criticalSection();
+       }
+   );
+
+   Snowflake::setSequenceProvider($provider);
+
+Custom Provider Contract
+------------------------
+
+Implement:
+
+.. code-block:: php
+
+   public function next(string $type, int $machineId, int $timestamp): int;
+
+The return value must be a non-negative integer sequence.
diff --git a/docs/snowflake.rst b/docs/snowflake.rst
new file mode 100644
index 0000000..54aa026
--- /dev/null
+++ b/docs/snowflake.rst
@@ -0,0 +1,96 @@
+Snowflake
+=========
+
+Class: ``Infocyph\\UID\\Snowflake``
+
+Bit Layout
+----------
+
+Snowflake follows a 64-bit layout:
+
+- 41 bits timestamp (ms from custom epoch)
+- 5 bits datacenter
+- 5 bits worker
+- 12 bits sequence
+
+Generation
+----------
+
+.. code-block:: php
+
+   <?php
+
+   use Infocyph\UID\Snowflake;
+
+   $id = Snowflake::generate();
+   $idFromNode = Snowflake::generate(datacenter: 1, workerId: 7);
+
+Configuration Object
+--------------------
+
+Use ``Infocyph\\UID\\Configuration\\SnowflakeConfig`` for advanced control:
+
+- fixed ``datacenterId`` and ``workerId``
+- ``nodeResolver`` callback
+- ``customEpoch`` (``DateTimeInterface`` | ``int`` ms | parseable date string)
+- custom ``sequenceProvider``
+- ``ClockBackwardPolicy`` (``WAIT`` or ``THROW``)
+- ``IdOutputType`` (``STRING``, ``INT``, ``BINARY``)
+
+.. code-block:: php
+
+   <?php
+
+   use Infocyph\UID\Configuration\SnowflakeConfig;
+   use Infocyph\UID\Enums\ClockBackwardPolicy;
+   use Infocyph\UID\Enums\IdOutputType;
+   use Infocyph\UID\Snowflake;
+
+   $config = new SnowflakeConfig(
+       datacenterId: 2,
+       workerId: 3,
+       customEpoch: '2020-01-01 00:00:00',
+       clockBackwardPolicy: ClockBackwardPolicy::WAIT,
+       outputType: IdOutputType::STRING,
+   );
+
+   $id = Snowflake::generateWithConfig($config);
+
+Validation and Parsing
+----------------------
+
+.. code-block:: php
+
+   <?php
+
+   use Infocyph\UID\Snowflake;
+
+   Snowflake::isValid($id);
+   $parsed = Snowflake::parse($id);
+
+``parse()`` output:
+
+- ``time`` (DateTimeImmutable)
+- ``sequence`` (int)
+- ``worker_id`` (int)
+- ``datacenter_id`` (int)
+
+Custom Epoch APIs
+-----------------
+
+- ``Snowflake::setStartTimeStamp('2020-01-01 00:00:00')``
+- ``Snowflake::parseWithEpoch($id, $epochMs)``
+
+Binary and Alternate Bases
+--------------------------
+
+- ``Snowflake::toBytes($id)`` / ``Snowflake::fromBytes($bytes)``
+- ``Snowflake::toBase($id, $base)`` / ``Snowflake::fromBase($encoded, $base)``
+
+Supported bases: ``16``, ``32``, ``36``, ``58``, ``62``.
+
+Exception Types
+---------------
+
+- ``Infocyph\\UID\\Exceptions\\SnowflakeException``
+- ``Infocyph\\UID\\Exceptions\\FileLockException``
diff --git a/docs/sonyflake.rst b/docs/sonyflake.rst
new file mode 100644
index 0000000..0f284e4
--- /dev/null
+++ b/docs/sonyflake.rst
@@ -0,0 +1,84 @@
+Sonyflake
+=========
+
+Class: ``Infocyph\\UID\\Sonyflake``
+
+Bit Layout
+----------
+
+Sonyflake uses a 64-bit layout:
+
+- 39 bits elapsed time in 10ms units from custom epoch
+- 16 bits machine ID
+- 8 bits sequence
+
+Generation
+----------
+
+.. code-block:: php
+
+   <?php
+
+   use Infocyph\UID\Sonyflake;
+
+   $id = Sonyflake::generate();
+   $idFromMachine = Sonyflake::generate(machineId: 42);
+
+Configuration Object
+--------------------
+
+Use ``Infocyph\\UID\\Configuration\\SonyflakeConfig`` for:
+
+- fixed or callback-resolved machine ID
+- custom epoch
+- custom sequence provider
+- clock-backward policy
+- output type (string/int/binary)
+
+.. code-block:: php
+
+   <?php
+
+   use Infocyph\UID\Configuration\SonyflakeConfig;
+   use Infocyph\UID\Sonyflake;
+
+   $config = new SonyflakeConfig(machineId: 42);
+   $id = Sonyflake::generateWithConfig($config);
+
+Validation and Parsing
+----------------------
+
+.. code-block:: php
+
+   <?php
+
+   use Infocyph\UID\Sonyflake;
+
+   Sonyflake::isValid($id);
+   $parsed = Sonyflake::parse($id);
+
+``parse()`` output:
+
+- ``time`` (DateTimeImmutable)
+- ``sequence`` (int)
+- ``machine_id`` (int)
+
+Custom Epoch APIs
+-----------------
+
+- ``Sonyflake::setStartTimeStamp('2020-01-01 00:00:00')``
+- ``Sonyflake::parseWithEpoch($id, $epochMs)``
+
+Binary and Alternate Bases
+--------------------------
+
+- ``Sonyflake::toBytes($id)`` / ``Sonyflake::fromBytes($bytes)``
+- ``Sonyflake::toBase($id, $base)`` / ``Sonyflake::fromBase($encoded, $base)``
+
+Supported bases: ``16``, ``32``, ``36``, ``58``, ``62``.
+
+Exception Types
+---------------
+
+- ``Infocyph\\UID\\Exceptions\\SonyflakeException``
+- ``Infocyph\\UID\\Exceptions\\FileLockException``
diff --git a/docs/tbsl.rst b/docs/tbsl.rst
new file mode 100644
index 0000000..8c0e574
--- /dev/null
+++ b/docs/tbsl.rst
@@ -0,0 +1,76 @@
+TBSL
+====
+
+Class: ``Infocyph\\UID\\TBSL``
+
+TBSL is a project-specific, time-based, lexicographically sortable uppercase hex ID.
+
+Format
+------
+
+- 20 hex chars (10 bytes)
+- ``TBSL::isValid()`` verifies ``^[0-9A-F]{20}$``
+
+Generation
+----------
+
+.. code-block:: php
+
+   <?php
+
+   use Infocyph\UID\TBSL;
+
+   $id = TBSL::generate();
+   $idWithMachine = TBSL::generate(machineId: 9);
+   $idWithSequence = TBSL::generate(machineId: 9, sequenced: true);
+
+Configuration Object
+--------------------
+
+Use ``Infocyph\\UID\\Configuration\\TBSLConfig`` for:
+
+- fixed or callback-resolved machine ID
+- toggling ``sequenced`` mode
+- custom sequence provider
+- clock-backward policy
+- output type (string/int/binary)
+
+.. code-block:: php
+
+   <?php
+
+   use Infocyph\UID\Configuration\TBSLConfig;
+   use Infocyph\UID\TBSL;
+
+   $config = new TBSLConfig(machineId: 9, sequenced: true);
+   $id = TBSL::generateWithConfig($config);
+
+Parsing
+-------
+
+.. code-block:: php
+
+   <?php
+
+   use Infocyph\UID\TBSL;
+
+   $parsed = TBSL::parse($id);
+
+``parse()`` output:
+
+- ``isValid`` (bool)
+- ``time`` (DateTimeImmutable|null)
+- ``machineId`` (int|null)
+
+Binary and Alternate Bases
+--------------------------
+
+- ``TBSL::toBytes($id)`` / ``TBSL::fromBytes($bytes)``
+- ``TBSL::toBase($id, $base)`` / ``TBSL::fromBase($encoded, $base)``
+
+Supported bases: ``16``, ``32``, ``36``, ``58``, ``62``.
+
+Exception Type
+--------------
+
+TBSL APIs throw ``Infocyph\\UID\\Exceptions\\UIDException`` for validation/runtime issues.
diff --git a/docs/ulid.rst b/docs/ulid.rst
new file mode 100644
index 0000000..3881247
--- /dev/null
+++ b/docs/ulid.rst
@@ -0,0 +1,51 @@
+ULID
+====
+
+Class: ``Infocyph\\UID\\ULID``
+
+ULID uses Crockford Base32 and produces 26-character sortable identifiers.
+
+Generation Modes
+----------------
+
+UID supports explicit generation modes via ``UlidGenerationMode``:
+
+- ``MONOTONIC`` (default)
+- ``RANDOM``
+
+.. code-block:: php
+
+   <?php
+
+   use Infocyph\UID\Enums\UlidGenerationMode;
+   use Infocyph\UID\ULID;
+
+   $default = ULID::generate();
+   $monotonic = ULID::generateMonotonic();
+   $random = ULID::generateRandom();
+   $explicit = ULID::generate(mode: UlidGenerationMode::RANDOM);
+
+Validation and Time Extraction
+------------------------------
+
+.. code-block:: php
+
+   <?php
+
+   use Infocyph\UID\ULID;
+
+   $ok = ULID::isValid($ulid);
+   $time = ULID::getTime($ulid); // DateTimeImmutable
+
+Binary and Alternate Bases
+--------------------------
+
+- ``ULID::toBytes($ulid)`` / ``ULID::fromBytes($bytes)``
+- ``ULID::toBase($ulid, $base)`` / ``ULID::fromBase($encoded, $base)``
+
+Supported bases: ``16``, ``32``, ``36``, ``58``, ``62``.
+
+Exception Type
+--------------
+
+ULID-specific failures throw ``Infocyph\\UID\\Exceptions\\ULIDException``.
diff --git a/docs/uuid.rst b/docs/uuid.rst
new file mode 100644
index 0000000..6892913
--- /dev/null
+++ b/docs/uuid.rst
@@ -0,0 +1,109 @@
+UUID
+====
+
+Class: ``Infocyph\\UID\\UUID``
+
+Supported Versions
+------------------
+
+- ``v1``: time-based
+- ``v3``: namespace + MD5
+- ``v4``: random
+- ``v5``: namespace + SHA-1
+- ``v6``: reordered time-based
+- ``v7``: Unix millisecond time-ordered
+- ``v8``: custom payload within UUID v8 envelope
+
+Generation
+----------
+
+.. code-block:: php
+
+   <?php
+
+   use DateTimeImmutable;
+   use Infocyph\UID\UUID;
+
+   $v1 = UUID::v1();
+   $v3 = UUID::v3('url', 'https://example.com');
+   $v4 = UUID::v4();
+   $v5 = UUID::v5('dns', 'example.com');
+   $v6 = UUID::v6();
+   $v7 = UUID::v7();
+   $v7AtTime = UUID::v7(new DateTimeImmutable('2026-01-01 00:00:00'));
+   $v8 = UUID::v8();
+
+Node-Aware Versions
+-------------------
+
+Versions ``v1``, ``v6``, ``v7``, and ``v8`` accept an optional node.
+If omitted, UID generates one.
+
+.. code-block:: php
+
+   <?php
+
+   use Infocyph\UID\UUID;
+
+   $node = UUID::getNode(); // 12 hex chars
+
+   $uuid = UUID::v7(null, $node);
+
+Canonical Utilities
+-------------------
+
+- ``UUID::normalize($uuid)``
+- ``UUID::compact($uuid)``
+- ``UUID::toUrn($uuid)``
+- ``UUID::toBraces($uuid)``
+- ``UUID::lowercase($uuid)``
+- ``UUID::uppercase($uuid)``
+
+NIL and MAX
+-----------
+
+- ``UUID::nil()``
+- ``UUID::max()``
+- ``UUID::isNil($uuid)``
+- ``UUID::isMax($uuid)``
+
+Validation and Parsing
+----------------------
+
+.. code-block:: php
+
+   <?php
+
+   use Infocyph\UID\UUID;
+
+   $ok = UUID::isValid($uuid);
+   $parts = UUID::parse($uuid);
+
+``UUID::parse()`` returns:
+
+- ``isValid`` (bool)
+- ``version`` (int|null)
+- ``variant`` (string|null)
+- ``time`` (DateTimeInterface|null)
+- ``node`` (string|null)
+- ``tail`` (string|null)
+
+For ``v7`` and ``v8``, ``node`` is intentionally ``null``.
+
+Binary and Alternate Bases
+--------------------------
+
+- ``UUID::toBytes($uuid)`` / ``UUID::fromBytes($bytes)``
+- ``UUID::toBase($uuid, $base)`` / ``UUID::fromBase($encoded, $base)``
+
+Supported bases: ``16``, ``32``, ``36``, ``58``, ``62``.
+
+GUID Helper
+-----------
+
+``UUID::guid(bool $trim = true)`` generates GUID-format text.
+
+Exception Type
+--------------
+
+UUID-specific failures throw ``Infocyph\\UID\\Exceptions\\UUIDException``.
diff --git a/docs/value-objects.rst b/docs/value-objects.rst
new file mode 100644
index 0000000..d56dad0
--- /dev/null
+++ b/docs/value-objects.rst
@@ -0,0 +1,60 @@
+Value Objects and Comparison
+============================
+
+Interface
+---------
+
+All value objects implement ``Infocyph\\UID\\Contracts\\IdValueInterface``:
+
+- ``toString()``
+- ``compare(IdValueInterface|string $other)``
+- ``getTimestamp(): ?DateTimeImmutable``
+- ``getMachineId(): int|string|null``
+- ``getVersion(): ?int``
+- ``isSortable(): bool``
+
+Available Value Classes
+-----------------------
+
+- ``Infocyph\\UID\\Value\\UuidValue``
+- ``Infocyph\\UID\\Value\\UlidValue``
+- ``Infocyph\\UID\\Value\\SnowflakeValue``
+- ``Infocyph\\UID\\Value\\SonyflakeValue``
+- ``Infocyph\\UID\\Value\\TbslValue``
+
+Using Value Objects
+-------------------
+
+.. code-block:: php
+
+   <?php
+
+   use Infocyph\UID\Id;
+
+   $uuid = Id::uuid7Value();
+   $ulid = Id::ulidValue();
+   $snowflake = Id::snowflakeValue();
+
+   $uuidText = $uuid->toString();
+   $uuidVersion = $uuid->getVersion();
+   $uuidTime = $uuid->getTimestamp();
+
+IdComparator
+------------
+
+``Infocyph\\UID\\IdComparator`` provides generic comparison/sorting:
+
+- ``compare(IdValueInterface|string $left, IdValueInterface|string $right): int``
+- ``sort(array $ids): array``
+
+When both values are digit-only, comparator uses unsigned-decimal ordering;
+otherwise it falls back to lexical comparison.
+
+.. code-block:: php
+
+   <?php
+
+   use Infocyph\UID\IdComparator;
+
+   $sorted = IdComparator::sort(['9', '10', '2']);
+   // ['2', '9', '10']