diff --git a/README.md b/README.md
index d66f45c..3de5d9f 100644
--- a/README.md
+++ b/README.md
@@ -29,6 +29,7 @@ libraryDependencies += "io.github.ramytanios" %% "json-schema-lib" % "<version>"
 - **Map support** - `Map[String, V]` maps to `{ "type": "object", "additionalProperties": ... }`
 - **Option support** - Optional fields automatically excluded from required list
 - **Circe integration** - Built-in JSON encoding for schemas
+- **`$schema` declaration** - Annotate the root schema with a JSON Schema draft URI via `withSchemaVersion`
 
 ## Example
 
@@ -56,13 +57,16 @@ case class Profile(
 // object Profile:
 //   given JsonSchema[Profile] = DeriveJsonSchema.derived
 
-val json = JsonSchema[Profile].schema.toJson
+val json = JsonSchema[Profile].schema
+  .withSchemaVersion(JsonSchemaVersion.Draft202012)
+  .toJson
 ```
 
 **Generated JSON Schema:**
 
 ```json
 {
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "title": "User profile",
   "properties": {
diff --git a/build.sbt b/build.sbt
index 906e256..a53cf2c 100644
--- a/build.sbt
+++ b/build.sbt
@@ -23,13 +23,15 @@ ThisBuild / scmInfo := Some(
 )
 
 lazy val V = new {
-  val circe = "0.14.15"
-  val munit = "1.2.1"
+  val circe      = "0.14.15"
+  val munit      = "1.2.1"
+  val http4s     = "0.23.30"
+  val catsEffect = "3.5.4"
 }
 
 lazy val root =
   (project in file("."))
-    .aggregate(libJVM, libJS)
+    .aggregate(libJVM, libJS, excel, excelExample)
     .settings(publish / skip := true)
 
 lazy val lib = crossProject(JSPlatform, JVMPlatform)
@@ -52,3 +54,31 @@ lazy val lib = crossProject(JSPlatform, JVMPlatform)
 
 lazy val libJVM = lib.jvm
 lazy val libJS = lib.js
+
+lazy val excel =
+  (project in file("excel"))
+    .dependsOn(libJVM)
+    .settings(
+      name := "json-schema-lib-excel",
+      libraryDependencies ++= Seq(
+        "io.circe"      %% "circe-core"   % V.circe,
+        "org.http4s"    %% "http4s-dsl"   % V.http4s,
+        "org.typelevel" %% "cats-effect"  % V.catsEffect,
+        "org.scalameta" %% "munit"        % V.munit % Test
+      ),
+      scalacOptions -= "-Xfatal-warnings"
+    )
+
+lazy val excelExample =
+  (project in file("excel-example"))
+    .dependsOn(excel)
+    .settings(
+      name := "json-schema-lib-excel-example",
+      publish / skip := true,
+      libraryDependencies ++= Seq(
+        "org.http4s"    %% "http4s-ember-server" % V.http4s,
+        "org.http4s"    %% "http4s-ember-client" % V.http4s,
+        "org.http4s"    %% "http4s-circe"        % V.http4s,
+      ),
+      scalacOptions -= "-Xfatal-warnings"
+    )
diff --git a/excel-example/manifest.xml b/excel-example/manifest.xml
new file mode 100644
index 0000000..671235b
--- /dev/null
+++ b/excel-example/manifest.xml
@@ -0,0 +1,137 @@
+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<!--
+Minimal Office Add-in manifest for sideloading ExcelMain in Excel.
+
+  Prerequisites:
+    1. Start the server:  sbt "excel/runMain jsonschema.excel.ExcelMain"
+    2. Verify it's up:    curl http://localhost:7777/functions.json
+
+Sideloading instructions:
+  https://learn.microsoft.com/en-us/office/dev/add-ins/testing/test-debug-office-add-ins
+
+  Functions exposed (all prefixed EXMAIN. in Excel):
+    =EXMAIN.ADD(x, y)
+    =EXMAIN.REPEAT(text, times, [sep])
+    =EXMAIN.FETCH_POST(id)
+    =EXMAIN.CURRENT_TEMP(lat, lon)
+-->
+<OfficeApp
+  xmlns="http://schemas.microsoft.com/office/appforoffice/1.1"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xmlns:bt="http://schemas.microsoft.com/office/officeappbasictypes/1.0"
+  xmlns:ov="http://schemas.microsoft.com/office/taskpaneappversionoverrides"
+  xsi:type="TaskPaneApp">
+
+  <!-- Unique add-in ID — regenerate if you deploy multiple instances -->
+  <Id>a1b2c3d4-e5f6-7890-abcd-ef1234567891</Id>
+  <Version>1.0.0.0</Version>
+  <ProviderName>ExcelMain (local dev)</ProviderName>
+  <DefaultLocale>en-US</DefaultLocale>
+  <DisplayName DefaultValue="ExcelMain Tst"/>
+  <Description DefaultValue="Custom functions served by local ExcelMain server"/>
+
+  <IconUrl DefaultValue="http://localhost:7777/icon-32.png"/>
+  <HighResolutionIconUrl DefaultValue="http://localhost:7777/icon-80.png"/>
+
+  <Hosts>
+    <Host Name="Workbook"/>
+  </Hosts>
+
+  <!-- Minimum requirement: CustomFunctionsRuntime 1.1 -->
+  <Requirements>
+    <Sets DefaultMinVersion="1.1">
+      <Set Name="CustomFunctionsRuntime"/>
+    </Sets>
+  </Requirements>
+
+  <DefaultSettings>
+    <!-- Task-pane host page -->
+    <SourceLocation DefaultValue="http://localhost:7777/taskpane.html"/>
+  </DefaultSettings>
+
+  <Permissions>ReadWriteDocument</Permissions>
+
+  <VersionOverrides xmlns="http://schemas.microsoft.com/office/taskpaneappversionoverrides"
+                    xsi:type="VersionOverridesV1_0">
+
+    <Hosts>
+      <Host xsi:type="Workbook">
+
+        <!-- Custom functions runtime (all form factors) -->
+        <AllFormFactors>
+          <ExtensionPoint xsi:type="CustomFunctions">
+            <Script>
+              <SourceLocation resid="FunctionsUrl"/>
+            </Script>
+            <Page>
+              <SourceLocation resid="HtmlUrl"/>
+            </Page>
+            <Metadata>
+              <SourceLocation resid="JsonUrl"/>
+            </Metadata>
+            <Namespace resid="Namespace"/>
+          </ExtensionPoint>
+        </AllFormFactors>
+
+        <!-- Ribbon button (desktop only) — note: singular DesktopFormFactor -->
+        <DesktopFormFactor>
+          <FunctionFile resid="FunctionsUrl"/>
+          <ExtensionPoint xsi:type="PrimaryCommandSurface">
+            <OfficeTab id="TabHome">
+              <Group id="ExMainGroup">
+                <Label resid="GroupLabel"/>
+                <Icon>
+                  <bt:Image size="16" resid="Icon16"/>
+                  <bt:Image size="32" resid="Icon32"/>
+                  <bt:Image size="80" resid="Icon80"/>
+                </Icon>
+                <Control xsi:type="Button" id="OpenTaskpane">
+                  <Label resid="TaskpaneButtonLabel"/>
+                  <Supertip>
+                    <Title resid="TaskpaneButtonLabel"/>
+                    <Description resid="TaskpaneButtonDesc"/>
+                  </Supertip>
+                  <Icon>
+                    <bt:Image size="16" resid="Icon16"/>
+                    <bt:Image size="32" resid="Icon32"/>
+                    <bt:Image size="80" resid="Icon80"/>
+                  </Icon>
+                  <Action xsi:type="ShowTaskpane">
+                    <TaskpaneId>ExMainTaskpane</TaskpaneId>
+                    <SourceLocation resid="TaskpaneUrl"/>
+                  </Action>
+                </Control>
+              </Group>
+            </OfficeTab>
+          </ExtensionPoint>
+        </DesktopFormFactor>
+
+      </Host>
+    </Hosts>
+
+    <Resources>
+      <bt:Images>
+        <bt:Image id="Icon16" DefaultValue="http://localhost:7777/icon-16.png"/>
+        <bt:Image id="Icon32" DefaultValue="http://localhost:7777/icon-32.png"/>
+        <bt:Image id="Icon80" DefaultValue="http://localhost:7777/icon-80.png"/>
+      </bt:Images>
+      <bt:Urls>
+        <bt:Url id="HtmlUrl"      DefaultValue="http://localhost:7777/functions.html"/>
+        <bt:Url id="FunctionsUrl" DefaultValue="http://localhost:7777/functions.js"/>
+        <bt:Url id="JsonUrl"      DefaultValue="http://localhost:7777/functions.json"/>
+        <bt:Url id="TaskpaneUrl"  DefaultValue="http://localhost:7777/taskpane.html"/>
+      </bt:Urls>
+      <bt:ShortStrings>
+        <bt:String id="Namespace"           DefaultValue="EXMAIN"/>
+        <bt:String id="GroupLabel"          DefaultValue="Functions"/>
+        <bt:String id="TaskpaneButtonLabel" DefaultValue="Function Reference"/>
+      </bt:ShortStrings>
+      <bt:LongStrings>
+        <bt:String id="TaskpaneButtonDesc"
+                   DefaultValue="Browse and search all available custom functions"/>
+      </bt:LongStrings>
+    </Resources>
+
+  </VersionOverrides>
+
+</OfficeApp>
diff --git a/excel-example/src/main/scala/jsonschema/excel/ExcelMain.scala b/excel-example/src/main/scala/jsonschema/excel/ExcelMain.scala
new file mode 100644
index 0000000..ee29425
--- /dev/null
+++ b/excel-example/src/main/scala/jsonschema/excel/ExcelMain.scala
@@ -0,0 +1,157 @@
+package jsonschema.excel
+
+import cats.data.OptionT
+import cats.effect.IO
+import cats.effect.IOApp
+import cats.effect.Resource
+import cats.syntax.semigroupk.*
+import com.comcast.ip4s.*
+import io.circe.Json
+import io.circe.syntax.*
+import jsonschema.Description
+import jsonschema.JsonSchema
+import org.http4s.HttpRoutes
+import org.http4s.Uri
+import org.http4s.circe.*
+import org.http4s.client.Client
+import org.http4s.dsl.io.*
+import org.http4s.ember.client.EmberClientBuilder
+import org.http4s.ember.server.EmberServerBuilder
+
+/**
+ * Example server for manual HTTP testing.
+ *
+ * Start with: sbt "excel-example/runMain jsonschema.excel.ExcelMain"
+ *
+ * Example invoke calls:
+ *   # pure computation
+ *   curl -s -X POST http://localhost:7777/invoke \
+ *     -H 'Content-Type: application/json' \
+ *     -d '{"functionId":"ADD","params":{"x":3,"y":4}}'
+ *
+ *   # calls jsonplaceholder.typicode.com
+ *   curl -s -X POST http://localhost:7777/invoke \
+ *     -H 'Content-Type: application/json' \
+ *     -d '{"functionId":"FETCH_POST","params":{"id":1}}'
+ *
+ *   # calls api.open-meteo.com (lat/lon for Paris)
+ *   curl -s -X POST http://localhost:7777/invoke \
+ *     -H 'Content-Type: application/json' \
+ *     -d '{"functionId":"CURRENT_TEMP","params":{"lat":48.85,"lon":2.35}}'
+ */
+object ExcelMain extends IOApp.Simple:
+
+  // ── Function input schemas ─────────────────────────────────────────────────
+
+  @Description("Add two numbers")
+  case class Add(
+      @Description("first operand") x: Double,
+      @Description("second operand") y: Double
+  ) derives JsonSchema
+
+  @Description("Repeat a string N times")
+  case class Repeat(
+      @Description("text to repeat") text: String,
+      @Description("number of repetitions") times: Int,
+      @Description("separator between repetitions (default: space)") sep: Option[String]
+  ) derives JsonSchema
+
+  @Description("Fetch the title of a JSONPlaceholder post")
+  case class FetchPost(
+      @Description("post ID between 1 and 100") id: Int
+  ) derives JsonSchema
+
+  @Description("Current temperature (°C) from Open-Meteo")
+  case class CurrentTemp(
+      @Description("latitude  (e.g. 48.85 for Paris, 40.71 for New York)") lat: Double,
+      @Description("longitude (e.g.  2.35 for Paris, -74.0 for New York)") lon: Double
+  ) derives JsonSchema
+
+  // ── Excel instance ─────────────────────────────────────────────────────────
+
+  private val excel = Excel(
+    functions = List(
+      ExcelFunctionBuilder.from[Add]("ADD"),
+      ExcelFunctionBuilder.from[Repeat]("REPEAT"),
+      ExcelFunctionBuilder.from[FetchPost]("FETCH_POST"),
+      ExcelFunctionBuilder.from[CurrentTemp]("CURRENT_TEMP")
+    ),
+    centralUrl = "http://localhost:7777/invoke",
+    namespace = "EXMAIN"
+  )
+
+  // ── Invoke routes ──────────────────────────────────────────────────────────
+
+  private def invokeRoutes(client: Client[IO]): HttpRoutes[IO] =
+    HttpRoutes.of[IO]:
+      case req @ POST -> Root / "invoke" =>
+        req.as[Json].flatMap: body =>
+          val c = body.hcursor
+          val fnId = c.get[String]("functionId").getOrElse("")
+          val params = c.downField("params")
+          fnId match
+            case "ADD" =>
+              (for
+                x <- params.get[Double]("x")
+                y <- params.get[Double]("y")
+              yield Ok((x + y).asJson))
+                .fold(e => BadRequest(e.message), identity)
+
+            case "REPEAT" =>
+              (for
+                text <- params.get[String]("text")
+                times <- params.get[Int]("times")
+                sep = params.get[String]("sep").toOption.getOrElse(" ")
+              yield Ok(List.fill(times)(text).mkString(sep).asJson))
+                .fold(e => BadRequest(e.message), identity)
+
+            case "FETCH_POST" =>
+              params
+                .get[Int]("id")
+                .fold(
+                  e => BadRequest(e.message),
+                  id =>
+                    client
+                      .expect[Json](
+                        Uri.unsafeFromString(s"https://jsonplaceholder.typicode.com/posts/$id")
+                      )
+                      .flatMap: json =>
+                        Ok(json.hcursor.get[String]("title").getOrElse("(no title)").asJson)
+                )
+
+            case "CURRENT_TEMP" =>
+              (for
+                lat <- params.get[Double]("lat")
+                lon <- params.get[Double]("lon")
+              yield
+                val uri = Uri
+                  .unsafeFromString("https://api.open-meteo.com/v1/forecast")
+                  .withQueryParam("latitude", lat)
+                  .withQueryParam("longitude", lon)
+                  .withQueryParam("current_weather", "true")
+                client
+                  .expect[Json](uri)
+                  .flatMap: json =>
+                    Ok(json.hcursor.downField(
+                      "current_weather"
+                    ).get[Double]("temperature").getOrElse(Double.NaN).asJson)
+              ).fold(e => BadRequest(e.message), identity)
+
+            case other =>
+              NotFound(s"unknown function: $other")
+
+  // ── Entry point ────────────────────────────────────────────────────────────
+
+  private def logged(routes: HttpRoutes[IO]): HttpRoutes[IO] =
+    HttpRoutes[IO](req => OptionT(IO.println(s"${req.method} ${req.uri}") *> routes(req).value))
+
+  def run: IO[Unit] =
+    EmberClientBuilder.default[IO].build.use: client =>
+      (Resource.eval(ExcelRoutes.routes(excel)).flatMap: addinRoutes =>
+        EmberServerBuilder
+          .default[IO]
+          .withHost(host"0.0.0.0")
+          .withPort(port"7777")
+          .withHttpApp((logged(addinRoutes) <+> logged(invokeRoutes(client))).orNotFound)
+          .build).use: srv =>
+        IO.println(s"Server running at http://${srv.address}") *> IO.never
diff --git a/excel/src/main/scala/jsonschema/excel/Excel.scala b/excel/src/main/scala/jsonschema/excel/Excel.scala
new file mode 100644
index 0000000..cc10e6d
--- /dev/null
+++ b/excel/src/main/scala/jsonschema/excel/Excel.scala
@@ -0,0 +1,26 @@
+package jsonschema.excel
+
+import io.circe.Json
+
+/**
+ * Represents an Excel add-in with a list of functions and a central URL for the add-in.
+ *
+ * @param functions
+ *   A list of Excel function definitions that the add-in provides.
+ * @param centralUrl
+ *   The URL used in the generated JavaScript to dispatch function calls.
+ * @param namespace
+ *   The Excel namespace prefix used in formula syntax (e.g. "EXMAIN" → =EXMAIN.ADD(...)). Should
+ *   match the Namespace resource in the add-in manifest.
+ */
+class Excel(functions: List[ExcelFunctionDef], centralUrl: String, namespace: String = ""):
+
+  def functionsJs(): String = ExcelJsGenerator.generate(functions, centralUrl, true)
+
+  def functionsJson(): Json = ExcelFunctionsManifest(functions).toJson
+
+  def functionsHtml(): String = ExcelHtml.functionsHtml
+
+  def taskpaneHtml(): String = ExcelHtml.taskpaneHtml(namespace)
+
+  def iconPng(size: Int): Array[Byte] = ExcelIcon.png(size)
diff --git a/excel/src/main/scala/jsonschema/excel/ExcelFunctionBuilder.scala b/excel/src/main/scala/jsonschema/excel/ExcelFunctionBuilder.scala
new file mode 100644
index 0000000..c038fc8
--- /dev/null
+++ b/excel/src/main/scala/jsonschema/excel/ExcelFunctionBuilder.scala
@@ -0,0 +1,35 @@
+package jsonschema.excel
+
+import io.circe.Json
+import jsonschema.JsonSchema
+
+object ExcelFunctionBuilder:
+
+  def from[A](id: String)(using js: JsonSchema[A]): ExcelFunctionDef =
+    val cursor = js.schema.toJson.hcursor
+    if cursor.get[String]("type").getOrElse("") != "object" then
+      throw IllegalArgumentException("ExcelFunctionBuilder.from requires a case class JsonSchema")
+    val description = cursor
+      .get[String]("description")
+      .getOrElse(throw IllegalArgumentException(
+        "ExcelFunctionBuilder.from requires a description in the JsonSchema"
+      ))
+    val required = cursor.downField("required").as[List[String]].getOrElse(Nil).toSet
+    val properties = cursor.downField("properties").as[Map[String, Json]].getOrElse(Map.empty)
+    val params =
+      properties.toList.sortBy((name, _) => (!required(name), name)).map: (name, fieldJson) =>
+        val fc = fieldJson.hcursor
+        val excelType = fc.get[String]("type").toOption match
+          case Some("string")  => ExcelParameterType.StringType
+          case Some("integer") => ExcelParameterType.NumberType
+          case Some("number")  => ExcelParameterType.NumberType
+          case Some("boolean") => ExcelParameterType.BooleanType
+          case _               => ExcelParameterType.AnyType
+        val desc = fc
+          .get[String]("description")
+          .toOption
+          .orElse(fc.get[String]("title").toOption)
+          .getOrElse("")
+        ExcelParameter(name, desc, excelType, !required(name))
+
+    ExcelFunctionDef(id, id, description, params)
diff --git a/excel/src/main/scala/jsonschema/excel/ExcelFunctionDef.scala b/excel/src/main/scala/jsonschema/excel/ExcelFunctionDef.scala
new file mode 100644
index 0000000..be9b925
--- /dev/null
+++ b/excel/src/main/scala/jsonschema/excel/ExcelFunctionDef.scala
@@ -0,0 +1,30 @@
+package jsonschema.excel
+
+import io.circe.Encoder
+import io.circe.Json
+import io.circe.JsonObject
+
+case class ExcelFunctionDef(
+    id: String,
+    name: String,
+    description: String,
+    parameters: List[ExcelParameter]
+)
+
+object ExcelFunctionDef:
+  given Encoder[ExcelFunctionDef] = Encoder.instance: fn =>
+    Json.fromJsonObject(
+      JsonObject(
+        "id" -> Json.fromString(fn.id),
+        "name" -> Json.fromString(fn.name),
+        "description" -> Json.fromString(fn.description),
+        "parameters" -> Encoder[List[ExcelParameter]].apply(fn.parameters),
+        "result" -> Json.fromJsonObject(JsonObject("type" -> Json.fromString("any"))),
+        "options" -> Json.fromJsonObject(
+          JsonObject(
+            "stream" -> Json.fromBoolean(false),
+            "cancelable" -> Json.fromBoolean(false)
+          )
+        )
+      )
+    )
diff --git a/excel/src/main/scala/jsonschema/excel/ExcelFunctionsManifest.scala b/excel/src/main/scala/jsonschema/excel/ExcelFunctionsManifest.scala
new file mode 100644
index 0000000..5298521
--- /dev/null
+++ b/excel/src/main/scala/jsonschema/excel/ExcelFunctionsManifest.scala
@@ -0,0 +1,11 @@
+package jsonschema.excel
+
+import io.circe.Encoder
+import io.circe.Json
+import io.circe.JsonObject
+
+case class ExcelFunctionsManifest(functions: List[ExcelFunctionDef]):
+  def toJson: Json =
+    Json.fromJsonObject(
+      JsonObject("functions" -> Encoder[List[ExcelFunctionDef]].apply(functions))
+    )
diff --git a/excel/src/main/scala/jsonschema/excel/ExcelHtml.scala b/excel/src/main/scala/jsonschema/excel/ExcelHtml.scala
new file mode 100644
index 0000000..42d04c5
--- /dev/null
+++ b/excel/src/main/scala/jsonschema/excel/ExcelHtml.scala
@@ -0,0 +1,163 @@
+package jsonschema.excel
+
+object ExcelHtml:
+
+  /** Minimal host page that bootstraps the custom-functions JS runtime. */
+  val functionsHtml: String =
+    """|<!DOCTYPE html>
+       |<html>
+       |  <head>
+       |    <meta charset="UTF-8"/>
+       |    <script src="https://appsforoffice.microsoft.com/lib/1/hosted/office.js"></script>
+       |  </head>
+       |  <body>
+       |    <script src="/functions.js"></script>
+       |  </body>
+       |</html>
+       |""".stripMargin
+
+  /** Task-pane reference page listing all registered functions. */
+  def taskpaneHtml(namespace: String): String =
+    val nsPrefix = if namespace.nonEmpty then s"$namespace." else ""
+    s"""|<!DOCTYPE html>
+        |<html>
+        |<head>
+        |  <meta charset="UTF-8"/>
+        |  <meta name="viewport" content="width=device-width, initial-scale=1"/>
+        |  <script src="https://appsforoffice.microsoft.com/lib/1/hosted/office.js"></script>
+        |  <style>${css}</style>
+        |</head>
+        |<body>
+        |  <div id="header">Function Reference</div>
+        |  <div id="search-box">
+        |    <input id="q" type="text" placeholder="Search functions…" oninput="doFilter()"/>
+        |  </div>
+        |  <div id="count"></div>
+        |  <div id="list"></div>
+        |  <div id="empty">No matching functions.</div>
+        |  <script>${js(nsPrefix)}</script>
+        |</body>
+        |</html>
+        |""".stripMargin
+
+  // ── Styles ──────────────────────────────────────────────────────────────────
+
+  private val css: String =
+    """|
+       |  * { box-sizing: border-box; }
+       |
+       |  body {
+       |    margin: 0;
+       |    font-family: 'Segoe UI', Tahoma, sans-serif;
+       |    font-size: 13px;
+       |    color: #323130;
+       |    background: #fff;
+       |  }
+       |
+       |  #header {
+       |    background: #217346;
+       |    color: #fff;
+       |    padding: 12px 14px;
+       |    font-size: 15px;
+       |    font-weight: 600;
+       |  }
+       |
+       |  #search-box {
+       |    padding: 8px 10px;
+       |    border-bottom: 1px solid #edebe9;
+       |  }
+       |
+       |  #search-box input {
+       |    width: 100%;
+       |    padding: 5px 8px;
+       |    border: 1px solid #c8c6c4;
+       |    border-radius: 2px;
+       |    font-size: 13px;
+       |    outline: none;
+       |  }
+       |
+       |  #search-box input:focus { border-color: #217346; }
+       |
+       |  #count {
+       |    padding: 4px 14px;
+       |    font-size: 11px;
+       |    color: #a19f9d;
+       |    background: #faf9f8;
+       |    border-bottom: 1px solid #edebe9;
+       |  }
+       |
+       |  .fn-card {
+       |    padding: 10px 14px;
+       |    border-bottom: 1px solid #edebe9;
+       |  }
+       |
+       |  .fn-card:hover { background: #f3f2f1; }
+       |
+       |  .fn-sig {
+       |    font-family: 'Cascadia Code', Consolas, monospace;
+       |    color: #217346;
+       |    font-weight: 600;
+       |    font-size: 12px;
+       |  }
+       |
+       |  .fn-desc { color: #605e5c; margin: 3px 0 5px; font-size: 12px; }
+       |
+       |  .params { list-style: none; padding: 0; margin: 0; }
+       |
+       |  .params li { font-size: 11px; color: #605e5c; padding: 1px 0; }
+       |
+       |  .pname { font-family: monospace; font-weight: 600; color: #323130; }
+       |
+       |  .popt { color: #a19f9d; font-style: italic; }
+       |
+       |  #empty { padding: 20px; text-align: center; color: #a19f9d; display: none; }
+       |""".stripMargin
+
+  // ── Client-side script ──────────────────────────────────────────────────────
+
+  private def js(nsPrefix: String): String =
+    s"""|
+        |  const NS_PREFIX = "$nsPrefix";
+        |  let fns = [];
+        |
+        |  function sig(f) {
+        |    const ps = f.parameters.map(p => p.optional ? "[" + p.name + "]" : p.name).join(", ");
+        |    return "=" + NS_PREFIX + f.name + "(" + ps + ")";
+        |  }
+        |
+        |  function card(f) {
+        |    const div = document.createElement("div");
+        |    div.className = "fn-card";
+        |    const ps = f.parameters.map(p => {
+        |      const opt = p.optional ? ' <span class="popt">(optional)</span>' : "";
+        |      const desc = p.description ? " — " + p.description : "";
+        |      return '<li><span class="pname">' + p.name + "</span>" + opt + desc + "</li>";
+        |    }).join("");
+        |    div.innerHTML =
+        |      '<div class="fn-sig">' + sig(f) + "</div>" +
+        |      '<div class="fn-desc">' + f.description + "</div>" +
+        |      (ps ? '<ul class="params">' + ps + "</ul>" : "");
+        |    return div;
+        |  }
+        |
+        |  function render(list) {
+        |    const el = document.getElementById("list");
+        |    el.innerHTML = "";
+        |    list.forEach(f => el.appendChild(card(f)));
+        |    document.getElementById("empty").style.display = list.length ? "none" : "block";
+        |    document.getElementById("count").textContent =
+        |      list.length + " function" + (list.length === 1 ? "" : "s");
+        |  }
+        |
+        |  function doFilter() {
+        |    const q = document.getElementById("q").value.toLowerCase();
+        |    render(q
+        |      ? fns.filter(f => f.name.toLowerCase().includes(q) || f.description.toLowerCase().includes(q))
+        |      : fns);
+        |  }
+        |
+        |  fetch("/functions.json").then(r => r.json()).then(data => {
+        |    fns = data.functions || [];
+        |    render(fns);
+        |  });
+        |""".stripMargin
diff --git a/excel/src/main/scala/jsonschema/excel/ExcelIcon.scala b/excel/src/main/scala/jsonschema/excel/ExcelIcon.scala
new file mode 100644
index 0000000..132e9c4
--- /dev/null
+++ b/excel/src/main/scala/jsonschema/excel/ExcelIcon.scala
@@ -0,0 +1,47 @@
+package jsonschema.excel
+
+import java.io.ByteArrayOutputStream
+import java.util.zip.CRC32
+import java.util.zip.Deflater
+
+/** Generates a solid-colour PNG icon at the requested pixel size. */
+object ExcelIcon:
+
+  def png(size: Int): Array[Byte] =
+    val ihdr = int32(size) ++ int32(size) ++ Array(8, 2, 0, 0, 0).map(_.toByte)
+    val out = ByteArrayOutputStream()
+    out.write(Array(0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a).map(_.toByte))
+    out.write(chunk("IHDR", ihdr))
+    out.write(chunk("IDAT", deflate(scanlines(size))))
+    out.write(chunk("IEND", Array.emptyByteArray))
+    out.toByteArray()
+
+  // ── Helpers ─────────────────────────────────────────────────────────────────
+
+  // Excel-green #217346 scanlines: filter-byte 0 followed by RGB pixels per row
+  private def scanlines(size: Int): Array[Byte] =
+    val raw = ByteArrayOutputStream(size * (1 + size * 3))
+    (0 until size).foreach: _ =>
+      raw.write(0)
+      (0 until size).foreach: _ =>
+        raw.write(0x21); raw.write(0x73); raw.write(0x46)
+    raw.toByteArray()
+
+  private def deflate(data: Array[Byte]): Array[Byte] =
+    val d = Deflater()
+    val buf = Array.ofDim[Byte](8192)
+    val out = ByteArrayOutputStream()
+    d.setInput(data)
+    d.finish()
+    while !d.finished() do out.write(buf, 0, d.deflate(buf))
+    out.toByteArray()
+
+  private def chunk(tag: String, data: Array[Byte]): Array[Byte] =
+    val tagBytes = tag.getBytes("US-ASCII")
+    val crc = CRC32()
+    crc.update(tagBytes)
+    crc.update(data)
+    int32(data.length) ++ tagBytes ++ data ++ int32(crc.getValue.toInt)
+
+  private def int32(n: Int): Array[Byte] =
+    Array((n >> 24).toByte, (n >> 16).toByte, (n >> 8).toByte, n.toByte)
diff --git a/excel/src/main/scala/jsonschema/excel/ExcelJsGenerator.scala b/excel/src/main/scala/jsonschema/excel/ExcelJsGenerator.scala
new file mode 100644
index 0000000..cbb3247
--- /dev/null
+++ b/excel/src/main/scala/jsonschema/excel/ExcelJsGenerator.scala
@@ -0,0 +1,43 @@
+package jsonschema.excel
+
+object ExcelJsGenerator:
+
+  private object Axios:
+
+    private val version = "1.14.0"
+    private val cdnUrl = s"https://cdn.jsdelivr.net/npm/axios@$version/dist/axios.min.js"
+    def jsSource(): String =
+      val conn = java.net.URI.create(cdnUrl).toURL.openConnection()
+      conn.setConnectTimeout(10_000)
+      conn.setReadTimeout(10_000)
+      scala.io.Source.fromInputStream(conn.getInputStream).mkString
+
+  private def renderFunction(fn: ExcelFunctionDef): String =
+    val paramNames = fn.parameters.map(_.name).mkString(", ")
+    val paramLines = fn.parameters.map(p => s"${p.name}: ${p.name},").mkString("\n")
+    s"""|CustomFunctions.associate(
+        |  "${fn.id}",
+        |  async function($paramNames) {
+        |    const response = await axios.post(CENTRAL_URL, {
+        |      functionId: "${fn.id}",
+        |      params: {
+        |         $paramLines
+        |      },
+        |    });
+        |    return response.data;
+        |  }
+        |);""".stripMargin
+
+  def generate(
+      functions: List[ExcelFunctionDef],
+      centralUrl: String,
+      selfContained: Boolean = false
+  ): String =
+    val bodies = functions.map(renderFunction).mkString("\n\n")
+    val core =
+      s"""|const CENTRAL_URL = "$centralUrl";
+          |
+          |$bodies
+          |""".stripMargin
+    if selfContained then s"${Axios.jsSource()}\n\n$core"
+    else core
diff --git a/excel/src/main/scala/jsonschema/excel/ExcelParameter.scala b/excel/src/main/scala/jsonschema/excel/ExcelParameter.scala
new file mode 100644
index 0000000..970b604
--- /dev/null
+++ b/excel/src/main/scala/jsonschema/excel/ExcelParameter.scala
@@ -0,0 +1,24 @@
+package jsonschema.excel
+
+import io.circe.Encoder
+import io.circe.Json
+import io.circe.JsonObject
+
+case class ExcelParameter(
+    name: String,
+    description: String,
+    `type`: ExcelParameterType,
+    optional: Boolean
+)
+
+object ExcelParameter:
+
+  given Encoder[ExcelParameter] = Encoder.instance: p =>
+    Json.fromJsonObject(
+      JsonObject(
+        "name" -> Json.fromString(p.name),
+        "description" -> Json.fromString(p.description),
+        "type" -> Encoder[ExcelParameterType].apply(p.`type`),
+        "optional" -> Json.fromBoolean(p.optional)
+      )
+    )
diff --git a/excel/src/main/scala/jsonschema/excel/ExcelParameterType.scala b/excel/src/main/scala/jsonschema/excel/ExcelParameterType.scala
new file mode 100644
index 0000000..1d17b50
--- /dev/null
+++ b/excel/src/main/scala/jsonschema/excel/ExcelParameterType.scala
@@ -0,0 +1,14 @@
+package jsonschema.excel
+
+import io.circe.Encoder
+
+enum ExcelParameterType:
+  case StringType, NumberType, BooleanType, AnyType
+
+object ExcelParameterType:
+
+  given Encoder[ExcelParameterType] = Encoder.encodeString.contramap:
+    case StringType  => "string"
+    case NumberType  => "number"
+    case BooleanType => "boolean"
+    case AnyType     => "any"
diff --git a/excel/src/main/scala/jsonschema/excel/ExcelRoutes.scala b/excel/src/main/scala/jsonschema/excel/ExcelRoutes.scala
new file mode 100644
index 0000000..82e4664
--- /dev/null
+++ b/excel/src/main/scala/jsonschema/excel/ExcelRoutes.scala
@@ -0,0 +1,35 @@
+package jsonschema.excel
+
+import cats.effect.IO
+import org.http4s.HttpRoutes
+import org.http4s.MediaType
+import org.http4s.dsl.io.*
+import org.http4s.headers.`Content-Type`
+
+object ExcelRoutes:
+
+  /** Builds the static-file routes for an [[Excel]] add-in, pre-computing all assets. */
+  def routes(excel: Excel): IO[HttpRoutes[IO]] =
+    for
+      js <- IO.blocking(excel.functionsJs())
+      json <- IO.pure(excel.functionsJson().noSpaces)
+      html <- IO.pure(excel.functionsHtml())
+      taskpane <- IO.pure(excel.taskpaneHtml())
+      icon16 <- IO.blocking(excel.iconPng(16))
+      icon32 <- IO.blocking(excel.iconPng(32))
+      icon80 <- IO.blocking(excel.iconPng(80))
+    yield HttpRoutes.of[IO]:
+      case GET -> Root / "functions.js" =>
+        Ok(js).map(_.withContentType(`Content-Type`(MediaType.unsafeParse("text/javascript"))))
+      case GET -> Root / "functions.json" =>
+        Ok(json).map(_.withContentType(`Content-Type`(MediaType.application.json)))
+      case GET -> Root / "functions.html" =>
+        Ok(html).map(_.withContentType(`Content-Type`(MediaType.text.html)))
+      case GET -> Root / "taskpane.html" =>
+        Ok(taskpane).map(_.withContentType(`Content-Type`(MediaType.text.html)))
+      case GET -> Root / "icon-16.png" =>
+        Ok(icon16).map(_.withContentType(`Content-Type`(MediaType.image.png)))
+      case GET -> Root / "icon-32.png" =>
+        Ok(icon32).map(_.withContentType(`Content-Type`(MediaType.image.png)))
+      case GET -> Root / "icon-80.png" =>
+        Ok(icon80).map(_.withContentType(`Content-Type`(MediaType.image.png)))
diff --git a/excel/src/test/scala/jsonschema/excel/ExcelFunctionBuilderTest.scala b/excel/src/test/scala/jsonschema/excel/ExcelFunctionBuilderTest.scala
new file mode 100644
index 0000000..f238cf3
--- /dev/null
+++ b/excel/src/test/scala/jsonschema/excel/ExcelFunctionBuilderTest.scala
@@ -0,0 +1,159 @@
+package jsonschema.excel
+
+import jsonschema.*
+import munit.FunSuite
+
+class ExcelFunctionBuilderTest extends FunSuite:
+
+  // ── Builder tests ──────────────────────────────────────────────────────────
+
+  test("all required fields → correct types, optional = false"):
+    @Description("req desc")
+    case class Req(name: String, count: Int, score: Double, flag: Boolean) derives JsonSchema
+    val fn = ExcelFunctionBuilder.from[Req]("REQ")
+    assertEquals(fn.parameters.map(_.name).toSet, Set("name", "count", "score", "flag"))
+    assertEquals(
+      fn.parameters.map(_.`type`).toSet,
+      Set(
+        ExcelParameterType.StringType,
+        ExcelParameterType.NumberType,
+        ExcelParameterType.NumberType,
+        ExcelParameterType.BooleanType
+      )
+    )
+    assert(fn.parameters.forall(!_.optional))
+
+  test("Option[T] fields → optional = true, inner type resolved correctly"):
+    @Description("opt desc")
+    case class Opt(name: String, count: Option[Int]) derives JsonSchema
+    val fn = ExcelFunctionBuilder.from[Opt]("OPT")
+    val countParam = fn.parameters.find(_.name == "count").get
+    assertEquals(countParam.optional, true)
+    assertEquals(countParam.`type`, ExcelParameterType.NumberType)
+
+  test("Int/Long → number, Double/Float → number"):
+    @Description("nums desc")
+    case class Nums(i: Int, l: Long, d: Double, f: Float) derives JsonSchema
+    val fn = ExcelFunctionBuilder.from[Nums]("NUMS")
+    assert(fn.parameters.forall(_.`type` == ExcelParameterType.NumberType))
+
+  test("Boolean → boolean"):
+    @Description("bools desc")
+    case class Bools(b: Boolean) derives JsonSchema
+    val fn = ExcelFunctionBuilder.from[Bools]("BOOLS")
+    assertEquals(fn.parameters.head.`type`, ExcelParameterType.BooleanType)
+
+  test("List, Map, nested case class → any; non-parameterized enum → string"):
+    case class Inner(x: Int) derives JsonSchema
+    enum Color derives JsonSchema:
+      case Red, Green, Blue
+    @Description("complex desc")
+    case class Complex(lst: List[String], mp: Map[String, Int], inner: Inner, color: Color)
+        derives JsonSchema
+    val fn = ExcelFunctionBuilder.from[Complex]("COMPLEX")
+    val anyParams = fn.parameters.filter(_.`type` == ExcelParameterType.AnyType)
+    assertEquals(anyParams.map(_.name).toSet, Set("lst", "mp", "inner"))
+    val colorParam = fn.parameters.find(_.name == "color").get
+    assertEquals(colorParam.`type`, ExcelParameterType.StringType)
+
+  test("@Description on field → description populated"):
+    @Description("described desc")
+    case class Described(@Description("The user name") name: String) derives JsonSchema
+    val fn = ExcelFunctionBuilder.from[Described]("DESC")
+    assertEquals(fn.parameters.head.description, "The user name")
+
+  test("@Title with no @Description → description falls back to title"):
+    @Description("titled desc")
+    case class Titled(@Title("User Name") name: String) derives JsonSchema
+    val fn = ExcelFunctionBuilder.from[Titled]("TITLE")
+    assertEquals(fn.parameters.head.description, "User Name")
+
+  test("no annotation → description = empty string"):
+    @Description("noanno desc")
+    case class NoAnno(name: String) derives JsonSchema
+    val fn = ExcelFunctionBuilder.from[NoAnno]("NOANNO")
+    assertEquals(fn.parameters.head.description, "")
+
+  test("required fields appear before optional in parameter list"):
+    @Description("mixed desc")
+    case class Mixed(id: Int, name: String, note: Option[String], extra: Option[Int])
+        derives JsonSchema
+    val fn = ExcelFunctionBuilder.from[Mixed]("MIXED")
+    val names = fn.parameters.map(_.name)
+    val reqIdx = names.indexOf("id").max(names.indexOf("name"))
+    val optIdx = names.indexOf("note").min(names.indexOf("extra"))
+    assert(reqIdx < optIdx)
+
+  test("non-ObjectSchema input → IllegalArgumentException"):
+    @annotation.nowarn("msg=unused local definition")
+    case class NotObject(value: String) derives JsonSchema
+    // Use an enum schema (non-object) directly
+    enum Color derives JsonSchema:
+      case Red, Green, Blue
+    intercept[IllegalArgumentException]:
+      ExcelFunctionBuilder.from[Color]("COLOR")
+
+  test("missing description in schema → IllegalArgumentException"):
+    case class NoDesc(x: String) derives JsonSchema
+    intercept[IllegalArgumentException]:
+      ExcelFunctionBuilder.from[NoDesc]("NODESC")
+
+  // ── Manifest test ──────────────────────────────────────────────────────────
+
+  test("ExcelFunctionsManifest.toJson wraps functions in {\"functions\": [...]}"):
+    @Description("simple desc")
+    case class Simple(x: String) derives JsonSchema
+    val fn = ExcelFunctionBuilder.from[Simple]("SIMPLE")
+    val manifest = ExcelFunctionsManifest(List(fn))
+    val json = manifest.toJson
+    assert(json.hcursor.downField("functions").focus.exists(_.isArray))
+    assertEquals(json.hcursor.downField("functions").as[List[io.circe.Json]].map(_.size), Right(1))
+
+  // ── JS generator tests ─────────────────────────────────────────────────────
+
+  test("ExcelJsGenerator.generate output contains const CENTRAL_URL header"):
+    val js = ExcelJsGenerator.generate(Nil, "https://example.com/route")
+    assert(js.contains("""const CENTRAL_URL = "https://example.com/route";"""))
+
+  test("generated JS uses axios.post and returns response.data"):
+    @Description("req2 desc")
+    case class Req2(ticker: String) derives JsonSchema
+    val fn = ExcelFunctionBuilder.from[Req2]("MY.FUNC")
+    val js = ExcelJsGenerator.generate(List(fn), "https://example.com")
+    assert(js.contains("CustomFunctions.associate("))
+    assert(js.contains(""""MY.FUNC""""))
+    assert(js.contains("async function(ticker)"))
+    assert(js.contains("axios.post(CENTRAL_URL"))
+    assert(js.contains("return response.data"))
+
+  test("request body shape: { functionId: ..., params: { field: field } }"):
+    @Description("req3 desc")
+    case class Req3(ticker: String, amount: Double) derives JsonSchema
+    val fn = ExcelFunctionBuilder.from[Req3]("MY.FUNC2")
+    val js = ExcelJsGenerator.generate(List(fn), "https://example.com")
+    assert(js.contains("""functionId: "MY.FUNC2""""))
+    assert(js.contains("ticker: ticker,"))
+    assert(js.contains("amount: amount,"))
+
+  test("selfContained = false does not include axios source inline"):
+    val js = ExcelJsGenerator.generate(Nil, "https://example.com", selfContained = false)
+    assert(!js.contains("axios/lib") && !js.contains("var axios"))
+
+  test("full round-trip: two functions, both CustomFunctions.associate calls present"):
+    @Description("Gets price")
+    case class PricingRequest(ticker: String, date: Option[String]) derives JsonSchema
+    @Description("Computes VaR")
+    case class RiskRequest(portfolio: String, confidence: Double) derives JsonSchema
+    val fns = List(
+      ExcelFunctionBuilder.from[PricingRequest]("PRICING.GET_PRICE"),
+      ExcelFunctionBuilder.from[RiskRequest]("RISK.COMPUTE_VAR")
+    )
+    val excel = new Excel(fns, "https://central-api.example.com/route")
+    val js = excel.`functionsJs`()
+    assert(js.contains(""""PRICING.GET_PRICE""""))
+    assert(js.contains(""""RISK.COMPUTE_VAR""""))
+    val manifestJson = excel.functionsJson()
+    assertEquals(
+      manifestJson.hcursor.downField("functions").as[List[io.circe.Json]].map(_.size),
+      Right(2)
+    )
diff --git a/lib/src/main/scala/jsonschema/Schema.scala b/lib/src/main/scala/jsonschema/Schema.scala
index 59ebf59..58ec747 100644
--- a/lib/src/main/scala/jsonschema/Schema.scala
+++ b/lib/src/main/scala/jsonschema/Schema.scala
@@ -10,6 +10,14 @@ import io.circe.JsonObject
 sealed trait Schema:
   def toJson: Json
 
+/**
+ * Represents a JSON Schema draft version, used to declare the `$schema` keyword on a root schema.
+ */
+enum JsonSchemaVersion(val uri: String):
+  case Draft07 extends JsonSchemaVersion("http://json-schema.org/draft-07/schema#")
+  case Draft201909 extends JsonSchemaVersion("https://json-schema.org/draft/2019-09/schema")
+  case Draft202012 extends JsonSchemaVersion("https://json-schema.org/draft/2020-12/schema")
+
 object Schema:
 
   given Encoder[Schema] = Encoder.instance(_.toJson)
@@ -35,6 +43,16 @@ object Schema:
     def withDescription(description: Option[String]): Schema =
       withOptionalStringField("description", description)
 
+    /**
+     * Add a `$schema` declaration to the schema.
+     * Should only be called on a root schema — nested schemas do not carry this field.
+     */
+    def withSchemaVersion(version: JsonSchemaVersion): Schema =
+      new Schema:
+        def toJson: Json =
+          val base = sch.toJson.asObject.getOrElse(JsonObject.empty)
+          Json.fromJsonObject(("$schema" -> Json.fromString(version.uri)) +: base)
+
   private def buildNumericJson[N](typeName: String, encode: N => Json)(
       minimum: Option[N],
       maximum: Option[N],
diff --git a/lib/src/test/scala/jsonschema/JsonSchemaTest.scala b/lib/src/test/scala/jsonschema/JsonSchemaTest.scala
index e8175d4..e5de8ba 100644
--- a/lib/src/test/scala/jsonschema/JsonSchemaTest.scala
+++ b/lib/src/test/scala/jsonschema/JsonSchemaTest.scala
@@ -225,3 +225,45 @@ class JsonSchemaTest extends FunSuite:
       }
     }""").getOrElse(io.circe.Json.Null)
     assertEquals(json, expected)
+
+  test("withSchemaVersion adds $schema as the first field (Draft-07)"):
+    val schema = JsonSchema[String].schema.withSchemaVersion(JsonSchemaVersion.Draft07)
+    val json = schema.toJson
+    val expected =
+      parse("""{"$schema": "http://json-schema.org/draft-07/schema#", "type": "string"}""")
+        .getOrElse(io.circe.Json.Null)
+    assertEquals(json, expected)
+    assertEquals(json.hcursor.keys.flatMap(_.headOption), Some("$schema"))
+
+  test("withSchemaVersion adds $schema as the first field (Draft 2019-09)"):
+    val schema = JsonSchema[Int].schema.withSchemaVersion(JsonSchemaVersion.Draft201909)
+    val json = schema.toJson
+    val expected =
+      parse("""{"$schema": "https://json-schema.org/draft/2019-09/schema", "type": "integer"}""")
+        .getOrElse(io.circe.Json.Null)
+    assertEquals(json, expected)
+    assertEquals(json.hcursor.keys.flatMap(_.headOption), Some("$schema"))
+
+  test("withSchemaVersion adds $schema as the first field (Draft 2020-12)"):
+    val schema = JsonSchema[Boolean].schema.withSchemaVersion(JsonSchemaVersion.Draft202012)
+    val json = schema.toJson
+    val expected =
+      parse("""{"$schema": "https://json-schema.org/draft/2020-12/schema", "type": "boolean"}""")
+        .getOrElse(io.circe.Json.Null)
+    assertEquals(json, expected)
+    assertEquals(json.hcursor.keys.flatMap(_.headOption), Some("$schema"))
+
+  test("withSchemaVersion composes with withTitle and withDescription"):
+    val schema = JsonSchema[String].schema
+      .withTitle(Some("My Schema"))
+      .withDescription(Some("A test schema"))
+      .withSchemaVersion(JsonSchemaVersion.Draft202012)
+    val json = schema.toJson
+    val expected = parse("""{
+      "$schema": "https://json-schema.org/draft/2020-12/schema",
+      "type": "string",
+      "title": "My Schema",
+      "description": "A test schema"
+    }""").getOrElse(io.circe.Json.Null)
+    assertEquals(json, expected)
+    assertEquals(json.hcursor.keys.flatMap(_.headOption), Some("$schema"))