Merge API into Docs (#5)

* update readme

* adds cursor rules

* Merge API into Docs

* cleanup internal helpers

* Rename registry app

* migrate registry to vercel

* revise registry deployment

* oops

* revert registry to cloudflare workers

Author: OllieJT

.cursor/rules/any-inside-generic-functions.mdc

@@ -0,0 +1,42 @@
+---
+description: 
+globs: *.ts,*.tsx
+alwaysApply: false
+---
+When building generic functions, you may need to use any inside the function body.
+
+This is because TypeScript often cannot match your runtime logic to the logic done inside your types.
+
+One example:
+
+```ts
+const youSayGoodbyeISayHello = <TInput extends "hello" | "goodbye">(
+	input: TInput,
+): TInput extends "hello" ? "goodbye" : "hello" => {
+	if (input === "goodbye") {
+		return "hello"; // Error!
+	} else {
+		return "goodbye"; // Error!
+	}
+};
+```
+
+On the type level (and the runtime), this function returns `goodbye` when the input is `hello`.
+
+There is no way to make this work concisely in TypeScript.
+
+So using `any` is the most concise solution:
+
+```ts
+const youSayGoodbyeISayHello = <TInput extends "hello" | "goodbye">(
+	input: TInput,
+): TInput extends "hello" ? "goodbye" : "hello" => {
+	if (input === "goodbye") {
+		return "hello" as any;
+	} else {
+		return "goodbye" as any;
+	}
+};
+```
+
+Outside of generic functions, use `any` extremely sparingly.

.cursor/rules/create-model.mdc

@@ -0,0 +1,123 @@
+---
+description:
+globs: packages/forge-models/src/**/*.ts,apps/docs/src/content/docs/models/**/*
+alwaysApply: false
+---
+# Rule: Create Model
+
+This rule outlines the process for defining new data models and ensuring their corresponding documentation is comprehensive and up-to-date. Adherence to this rule maintains clarity and consistency across the DH Forge System.
+
+## Core Principle
+
+Model definitions and their documentation are inextricably linked. **Whenever a model is created or modified, its documentation must be created or updated accordingly.**
+
+## Model Definition
+
+1.  **Location:** All core data models are defined as Zod schemas within the `/packages/forge-models/src/` directory.
+2.  - Models are stored within versioned folders (e.g., `/src/version-0.2`. `/src/version-1.0`)
+    - Organize models logically, potentially by category (e.g., `character/`, `item/`, `ability/`).
+    - Follow existing patterns or create new categorized subdirectories if appropriate.
+3.  **Technology:** Use @Zod schema definition and validation.
+4.  **Naming Conventions:**
+    - **Zod Schema Variable:** `camelCase` (e.g., `characterSchema`).
+    - **Exported Type:** `PascalCase` (e.g., `Character`), typically inferred from the Zod schema using `z.infer<typeof yourSchemaName>`.
+    - **File Names (for Zod schemas):** `kebab-case.ts` (e.g., `character.ts` or `item-schemas.ts`).
+
+## Documentation
+
+Each distinct model type _must_ have its own documentation page.
+
+1.  **Location:** `apps/docs/src/content/docs/models/`
+2.  **File Creation:**
+    - Create a new `.mdx` file for the model (e.g., `character.mdx` or `primary-class.mdx`).
+    - Use `kebab-case` for documentation filenames.
+3.  **Content Requirements:**
+    The `.mdx` file for each model must include:
+
+    - **Frontmatter:**
+      - `title`: A clear, descriptive title for the model (e.g., `Character Model`).
+      - `description`: A brief overview of what this model represents.
+    - **Main Content:**
+      - **Description Section:**
+        - A concise explanation of what the model represents and its purpose within the DH Forge System.
+        - Clarify any potential ambiguities.
+      - **Schema and Expected Values Section:**
+        - Detail all fields, their expected data types (e.g., string, number, boolean, array, nested object).
+        - Specify if fields are required or optional.
+        - Describe any constraints, enumerations (e.g., "must be one of 'VALUE_A', 'VALUE_B'"), or formatting rules.
+        - This section should accurately reflect the Zod schema. Including a relevant snippet of the Zod schema definition or a simplified representation is highly encouraged.
+      - **Examples Section:**
+        - Provide at least one, preferably multiple, clear JSON or TypeScript object examples illustrating valid instances of the model.
+        - Include examples that cover common use cases and demonstrate the use of optional fields.
+
+    **Example `.mdx` Structure:**
+
+    ````mdx
+    ---
+    title: Example Model Name
+    description: A brief overview of what this Example Model represents and its role in the system.
+    ---
+
+    ## Description
+
+    The `ExampleModel` is used to structure data related to [...]. Its primary purpose is to ensure consistency and provide a clear definition for [...].
+
+    ## Schema and Expected Values
+
+    The `ExampleModel` has the following structure:
+
+    | key                | type                | required | note                                                                                 |
+    |--------------------|---------------------|----------|--------------------------------------------------------------------------------------|
+    | id                 | string              | yes      | Unique identifier for the instance. Must follow UUID v4 format.                      |
+    | name               | string              | yes      | Human-readable name for the instance.                                                |
+    | status             | string              | yes      | Current status. Must be one of `ACTIVE`, `INACTIVE`, `PENDING`.                      |
+    | configuration      | object              | no       | Optional object containing further configuration details.                             |
+    | configuration.retries   | number         | no       | Number of retries, defaults to 3.                                                    |
+    | configuration.isEnabled | boolean        | yes      | Flag to enable or disable.                                                           |
+    | tags               | array of strings    | no       | List of associated tags.                                                             |
+
+    ## Examples
+
+    ### Basic Example
+
+    ```json
+    {
+      "id": "123e4567-e89b-12d3-a456-426614174000",
+      "name": "My First Example Instance",
+      "status": "ACTIVE"
+    }
+    ```
+    ````
+
+    ### Example with Optional Fields
+
+    ```json
+    {
+      "id": "987e6543-e21b-32d1-b432-872251234011",
+      "name": "Another Example Instance",
+      "status": "PENDING",
+      "configuration": {
+        "retries": 5,
+        "isEnabled": true
+      },
+      "tags": ["important", "needs-review"]
+    }
+    ```
+
+    ```
+
+    ```
+
+4.  **Referencing Other Models:**
+    - If the model references other models (e.g., using an ID that corresponds to another model, or the `category/type:id` convention if applicable), clearly explain these relationships.
+    - Where appropriate, link to the documentation pages for any referenced models.
+
+## Process Summary
+
+1.  **Define/Update Schema:** Create or modify the Zod schema in the relevant file within `/packages/forge-models/src/`.
+2.  **Create/Update Documentation:**
+    - Create a new `.mdx` file in `apps/docs/src/content/docs/models/` for a new model, or open the existing one for an update.
+    - Ensure the filename is `kebab-case`.
+3.  **Write Documentation Content:** Populate the `.mdx` file with the title, description, schema details, and examples as outlined above.
+4.  **Verify Accuracy:** Double-check that the documentation accurately reflects the current model schema.
+5.  **Commit Changes:** Commit both the schema changes (in `/packages/forge-models/`) and the documentation changes (in `apps/docs/src/content/docs/models/`) together in the same commit to ensure atomicity.

.cursor/rules/default-exports.mdc

@@ -0,0 +1,41 @@
+---
+description: 
+globs: *.ts,*.tsx
+alwaysApply: false
+---
+Unless explicitly required by the framework, do not use default exports.
+
+```ts
+// BAD
+export default function myFunction() {
+  return <div>Hello</div>;
+}
+```
+
+```ts
+// GOOD
+export function myFunction() {
+  return <div>Hello</div>;
+}
+```
+
+Default exports create confusion from the importing file.
+
+```ts
+// BAD
+import myFunction from "./myFunction";
+```
+
+```ts
+// GOOD
+import { myFunction } from "./myFunction";
+```
+
+There are certain situations where a framework may require a default export. For instance, Next.js requires a default export for pages.
+
+```tsx
+// This is fine, if required by the framework
+export default function MyPage() {
+	return <div>Hello</div>;
+}
+```

.cursor/rules/discriminated-unions.mdc

@@ -0,0 +1,57 @@
+---
+description: 
+globs: *.ts,*.tsx
+alwaysApply: false
+---
+Proactively use discriminated unions to model data that can be in one of a few different shapes.
+
+For example, when sending events between environments:
+
+```ts
+type UserCreatedEvent = {
+	type: "user.created";
+	data: { id: string; email: string };
+};
+
+type UserDeletedEvent = {
+	type: "user.deleted";
+	data: { id: string };
+};
+
+type Event = UserCreatedEvent | UserDeletedEvent;
+```
+
+Use switch statements to handle the results of discriminated unions:
+
+```ts
+const handleEvent = (event: Event) => {
+	switch (event.type) {
+		case "user.created":
+			console.log(event.data.email);
+			break;
+		case "user.deleted":
+			console.log(event.data.id);
+			break;
+	}
+};
+```
+
+Use discriminated unions to prevent the 'bag of optionals' problem.
+
+For example, when describing a fetching state:
+
+```ts
+// BAD - allows impossible states
+type FetchingState<TData> = {
+	status: "idle" | "loading" | "success" | "error";
+	data?: TData;
+	error?: Error;
+};
+
+// GOOD - prevents impossible states
+type FetchingState<TData> =
+	| { status: "idle" }
+	| { status: "loading" }
+	| { status: "success"; data: TData }
+	| { status: "error"; error: Error };
+```

.cursor/rules/enums.mdc

@@ -0,0 +1,47 @@
+---
+description: 
+globs: *.ts,*.tsx
+alwaysApply: false
+---
+Do not introduce new enums into the codebase. Retain existing enums.
+
+If you require enum-like behaviour, use an `as const` object:
+
+```ts
+const backendToFrontendEnum = {
+	xs: "EXTRA_SMALL",
+	sm: "SMALL",
+	md: "MEDIUM",
+} as const;
+
+type LowerCaseEnum = keyof typeof backendToFrontendEnum; // "xs" | "sm" | "md"
+
+type UpperCaseEnum = (typeof backendToFrontendEnum)[LowerCaseEnum]; // "EXTRA_SMALL" | "SMALL" | "MEDIUM"
+```
+
+Remember that numeric enums behave differently to string enums. Numeric enums produce a reverse mapping:
+
+```ts
+enum Direction {
+	Up,
+	Down,
+	Left,
+	Right,
+}
+
+const direction = Direction.Up; // 0
+const directionName = Direction[0]; // "Up"
+```
+
+This means that the enum `Direction` above will have eight keys instead of four.
+
+```ts
+enum Direction {
+	Up,
+	Down,
+	Left,
+	Right,
+}
+
+Object.keys(Direction).length; // 8
+```

.cursor/rules/import-type.mdc

@@ -0,0 +1,28 @@
+---
+description: 
+globs: *.ts,*.tsx
+alwaysApply: false
+---
+Use import type whenever you are importing a type.
+
+Prefer top-level `import type` over inline `import { type ... }`.
+
+```ts
+// BAD
+import { type User } from "./user";
+```
+
+```ts
+// GOOD
+import type { User } from "./user";
+```
+
+The reason for this is that in certain environments, the first version's import will not be erased. So you'll be left with:
+
+```ts
+// Before transpilation
+import { type User } from "./user";
+
+// After transpilation
+import "./user";
+```

.cursor/rules/installing-libraries.mdc

@@ -0,0 +1,17 @@
+---
+description: 
+globs: 
+alwaysApply: true
+---
+When installing libraries, do not rely on your own training data.
+
+Your training data has a cut-off date. You're probably not aware of all of the latest developments in the JavaScript and TypeScript world.
+
+This means that instead of picking a version manually (via updating the `package.json` file), you should use a script to install the latest version of a library.
+
+```bash
+# pnpm
+pnpm add -D @typescript-eslint/eslint-plugin
+```
+
+This will ensure you're always using the latest version.