diff --git a/mods/README.md b/mods/README.md
@@ -0,0 +1,46 @@
+# Command Code mods registry
+
+[`registry.json`](./registry.json) in this folder is the community registry behind the
+[mods hub](https://commandcode.ai/mods). The hub reads it live, so a merged PR here lists
+your mod within minutes — no website deploy.
+
+Two ways a mod gets listed:
+
+1. **Publish to npm with the `cmd-mod` keyword** — it is discovered automatically, no PR needed.
+2. **Open a PR against `registry.json`** — for git-only mods, or to add richer metadata. This is that path.
+
+## Add your mod
+
+Append one entry to the `mods` array in [`registry.json`](./registry.json). Editors validate it
+against [`registry.schema.json`](./registry.schema.json).
+
+```json
+{
+  "name": "cmd-mod-standup",
+  "source": "owner/cmd-mod-standup",
+  "description": "Adds a /standup command that summarizes what changed in git today.",
+  "author": { "name": "Jane Dev", "github": "janedev" },
+  "repo": "https://github.com/owner/cmd-mod-standup",
+  "npm": "cmd-mod-standup",
+  "kinds": ["command"],
+  "tags": ["git", "productivity"]
+}
+```
+
+### Fields
+
+| Field | Required | Notes |
+|-------|:---:|-------|
+| `name` | yes | unique, lowercase `[a-z0-9._-]` — the hub's identity for the row |
+| `source` | yes | what `cmd mods add <source> -g` installs: an npm name, `owner/repo`, or a `git:` URL |
+| `description` | yes | 1–240 chars; the card summary |
+| `author` | yes | `{ "name": "…" }` required; optional `github` / `url` link the name |
+| `kinds` | yes | one or more of `tool` `command` `hook` `provider` `renderer` `flag` |
+| `repo` | no | a GitHub URL also enables the star count |
+| `npm` | no | links the entry to its npm package for live download counts |
+| `tags` | no | lowercase slugs, searchable |
+| `addedAt` | no | `YYYY-MM-DD`, used for the "Newest" sort |
+
+`official` and the top-level `hidden` list are maintainer-only — leave them out of your PR.
+
+Keep the array valid JSON (no trailing commas) and one mod per PR where you can, so review stays quick.
diff --git a/mods/registry.json b/mods/registry.json
@@ -0,0 +1,19 @@
+{
+	"$schema": "./registry.schema.json",
+	"version": 1,
+	"hidden": [],
+	"mods": [
+		{
+			"name": "cmd-mod-hi",
+			"source": "cmd-mod-hi",
+			"description": "Roasts you every time you greet your agent with \"hi\". One transformInput hook plus a renderer, and a /hi-stats command that tallies the damage.",
+			"author": { "name": "Ahmad Awais", "github": "ahmadawais" },
+			"repo": "https://github.com/ahmadawais/cmd-mod-hi",
+			"npm": "cmd-mod-hi",
+			"kinds": ["hook", "command", "renderer"],
+			"tags": ["fun", "example"],
+			"official": true,
+			"addedAt": "2026-07-22"
+		}
+	]
+}
diff --git a/mods/registry.schema.json b/mods/registry.schema.json
@@ -0,0 +1,96 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"title": "Command Code mods registry",
+	"description": "The curated layer behind commandcode.ai/mods. Packages published to npm with the `cmd-mod` keyword are listed automatically; this file adds git-only mods, richer metadata over npm entries (matched by `npm`), and the `hidden` list for moderation. The resolved list is served at https://commandcode.ai/mods.json.",
+	"type": "object",
+	"required": ["version", "mods"],
+	"properties": {
+		"$schema": { "type": "string" },
+		"version": { "type": "integer", "const": 1 },
+		"hidden": {
+			"type": "array",
+			"uniqueItems": true,
+			"items": { "type": "string" },
+			"description": "Mod names (or npm package names) to keep off the hub — spam, malware, impersonation."
+		},
+		"mods": {
+			"type": "array",
+			"items": {
+				"type": "object",
+				"required": [
+					"name",
+					"source",
+					"description",
+					"author",
+					"kinds"
+				],
+				"additionalProperties": false,
+				"properties": {
+					"name": {
+						"type": "string",
+						"description": "Display name, and the name `cmd mods list` prints.",
+						"pattern": "^[a-z0-9][a-z0-9._-]*$"
+					},
+					"source": {
+						"type": "string",
+						"description": "What `cmd mods add <source>` takes: an npm name (`cmd-mod-hi`, `@team/mod`), or GitHub shorthand (`owner/repo`)."
+					},
+					"description": { "type": "string", "maxLength": 240 },
+					"author": {
+						"type": "object",
+						"required": ["name"],
+						"additionalProperties": false,
+						"properties": {
+							"name": { "type": "string" },
+							"github": {
+								"type": "string",
+								"description": "GitHub login."
+							},
+							"url": { "type": "string", "format": "uri" }
+						}
+					},
+					"repo": {
+						"type": "string",
+						"format": "uri",
+						"description": "Public git repository URL. GitHub repos get a live star count."
+					},
+					"npm": {
+						"type": "string",
+						"description": "npm package name when published to npm. Drives the monthly download count."
+					},
+					"kinds": {
+						"type": "array",
+						"minItems": 1,
+						"uniqueItems": true,
+						"items": {
+							"type": "string",
+							"enum": [
+								"tool",
+								"command",
+								"hook",
+								"provider",
+								"renderer",
+								"flag"
+							]
+						},
+						"description": "What the mod registers on the ModApi."
+					},
+					"tags": {
+						"type": "array",
+						"uniqueItems": true,
+						"items": { "type": "string", "pattern": "^[a-z0-9-]+$" }
+					},
+					"official": {
+						"type": "boolean",
+						"description": "Maintained by the Command Code team."
+					},
+					"addedAt": {
+						"type": "string",
+						"format": "date",
+						"description": "ISO date the mod was listed."
+					}
+				}
+			}
+		}
+	}
+}