@uniformdev/uniform-mcp 20.14.2-alpha.69 → 20.20.3

package/dist/index.mjs

@@ -61438,8 +61438,7 @@ var ChipContainer = css`
   }
 
   &:hover {
-    [role='presentation'],
-    [role='separator'] {
+    [role='presentation'] {
       transition: opacity var(--duration-fast) var(--timing-ease-out);
       opacity: var(--opacity-100);
     }
@@ -61451,8 +61450,7 @@ var ChipContainer = css`
   }
 
   :where([aria-disabled='true'], :disabled):hover {
-    [role='presentation'],
-    [role='separator'] {
+    [role='presentation'] {
       opacity: var(--opacity-50);
       cursor: not-allowed;
     }
@@ -61469,12 +61467,6 @@ var ChipIcon = css`
   display: flex;
   opacity: var(--opacity-50);
 `;
-var ChipSeparator = css`
-  display: flex;
-  border-right: 1px solid var(--white);
-  opacity: var(--opacity-50);
-  margin-left: -1px;
-`;
 var ChipSmall = css`
   font-size: var(--fs-sm);
   padding-inline: var(--spacing-sm);
@@ -66515,7 +66507,7 @@ async function applyCompositionPatches(existingComposition, deletedComponentsInS
           type: parameterEdit.update.parameterType
         };
         const property = properties[parameterEdit.update.parameterId];
-        const newValue = parameterEdit.propertyDefinition.type === "richText" ? convertMarkdownToLexical(parameterEdit.result.newValue) : parameterEdit.result.treatNewValueAsJson ? JSON.parse(parameterEdit.result.newValue) : parameterEdit.result.newValue;
+        const newValue = parameterEdit.propertyDefinition.type === "richText" ? convertMarkdownToLexical(parameterEdit.result.newValue) : parameterEdit.propertyDefinition.type === "number" ? Number(parameterEdit.result.newValue) : parameterEdit.result.treatNewValueAsJson ? JSON.parse(parameterEdit.result.newValue) : parameterEdit.result.newValue;
         if (parameterEdit.update.locale) {
           property.locales ??= {};
           property.locales[parameterEdit.update.locale] = newValue;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniformdev/uniform-mcp",
-  "version": "20.14.2-alpha.69+5c5fa31b75",
+  "version": "20.20.3",
   "description": "Uniform MCP Server",
   "license": "SEE LICENSE IN LICENSE.txt",
   "bin": {
@@ -28,21 +28,22 @@
     "@lexical/rich-text": "0.25.0",
     "@lexical/table": "0.25.0",
     "@modelcontextprotocol/sdk": "^1.12.0",
-    "@uniformdev/canvas": "20.14.2-alpha.69+5c5fa31b75",
+    "@uniformdev/canvas": "20.20.3",
     "fast-json-patch": "^3.1.1",
     "immer": "10.1.1",
     "lexical": "0.25.0",
     "zod": "3.23.8"
   },
   "files": [
-    "/dist"
+    "/dist",
+    "/references/*.mdc"
   ],
   "publishConfig": {
     "access": "public"
   },
   "devDependencies": {
-    "@uniformdev/design-system": "^20.14.2-alpha.69+5c5fa31b75",
+    "@uniformdev/design-system": "^20.20.3",
     "vitest": "^3.1.4"
   },
-  "gitHead": "5c5fa31b757bcb9cbfe0ce6934f6ee743319f8cb"
+  "gitHead": "3e58ece2c26439f3ee48d2ff445898a3be59b349"
 }

package/references/uniform-next-page-router.mdc

@@ -0,0 +1,314 @@
+---
+description: Uniform React Next Page Router Developer Reference - details how to use Uniform with React.js with Next Page Router
+globs:
+alwaysApply: true
+---
+
+[uniform.mdc](mdc:.cursor/rules/uniform.mdc) describes general Uniform principles and practices.
+[uniform-sdk.mdc](mdc:.cursor/rules/uniform-sdk.mdc) describes framework-agnostic developer principles.
+[uniform-context-sdk.mdc](mdc:references/uniform-context-sdk.mdc) describes personalization and a/b testing developer practices.
+
+### Required npm packages
+
+The following npm packages must be installed to wire Uniform CMS to Next Page Router:
+
+@uniformdev/canvas
+@uniformdev/canvas-react
+@uniformdev/canvas-next
+@uniformdev/context-react
+
+### Fetching and rendering the composition
+
+In your dynamic catch-all route file (`pages/[[...path]].{tsx|jsx}`), it is necessary to fetch the Uniform composition instance for the current route. This is done for server-side rendering using the `withUniformGetServerSideProps` function:
+
+```tsx
+import type { UniformCompositionNextPage } from "@uniformdev/canvas-next";
+import { withUniformGetServerSideProps } from "@uniformdev/canvas-next/route";
+import { UniformComposition } from "@uniformdev/canvas-react";
+
+// fetch the composition using SSR
+export const getServerSideProps = withUniformGetServerSideProps();
+
+// the function provides the composition to the route component as the `data` prop
+// the UniformCompositionNextPage type provides typings to make sure that is clear
+const page: UniformCompositionNextPage = ({ data }) => {
+  // the UniformComposition component takes over rendering the components on the composition data
+  return <UniformComposition data={data} />;
+};
+
+export { page as default };
+```
+
+### Rendering Uniform Components using React Components
+
+> IMPORTANT: before generating Uniform component code, always fetch available component definitions from Uniform to be aware of the schema.
+
+The `UniformComposition` component needs to know how to map a Uniform Component instance's `type` to a React component that implements the UI for that component. This is done using the Component Registry. To use the component registry, create a component and register it:
+
+`components/Hero.tsx`:
+
+```tsx
+import { registerUniformComponent } from "@uniformdev/canvas-react";
+
+function Hero() {
+  return <div>Hero Component Content</div>;
+}
+
+registerUniformComponent({
+  type: "hero",
+  component: Hero,
+});
+```
+Conventionally Uniform components (like Hero.tsx above) are imported to a barrel file in `components/uniformComponents.ts` (e.g. `import 'componentFileName';`), and that barrel file is imported into `_app.tsx` (e.g. `import '../components/uniformComponents';`) to ensure the registrations are processed.
+
+#### Mapping Uniform Components to React Components
+
+React components that receive Uniform Component data are passed props that correspond to the shape of the component definition they render. The `ComponentProps` type can be used to make the mapping explicit:
+
+```tsx
+import {
+  AssetParamValue,
+  LinkParamValue,
+  RichTextParamValue,
+} from "@uniformdev/canvas";
+
+type HeroProps = ComponentProps<{
+  textParameter?: string;
+  richTextParameter?: RichTextParamValue;
+  linkParameter?: LinkParamValue;
+  assetParameter?: AssetParamValue;
+  // it is critical that all parameter props values are optional, because they can be undefined - even if 'required' on the component definition
+}>;
+
+function Hero(props: HeroProps) {
+  return <div>{props.textParameter}</div>;
+}
+```
+
+#### Rendering child slots
+
+If a Uniform Component definition has slots defined, the components in those slots can be rendered using the `UniformSlot` component.
+
+```tsx
+import { UniformSlot } from "@uniformdev/canvas-react";
+
+function Hero() {
+  return (
+    <div>
+      <div>
+        <UniformSlot name="start" />
+      </div>
+      <div>
+        <UniformSlot name="end" />
+      </div>
+    </div>
+  );
+}
+```
+
+#### Rendering parameter/field values
+
+##### Text parameters/fields
+
+When rendering a `text` type parameter, always use the `UniformText` component to render the value. This will enable authors to edit the value within the Uniform preview directly. Text parameters that do not have a visible component, such as alt text, should be rendered as their raw text value:
+
+```tsx
+import { UniformText } from "@uniformdev/canvas-react";
+
+function Hero() {
+  return (
+    <div>
+      {/* always specify placeholder text that an author will see in the visual editor when the value is empty */}
+      <UniformText parameterId="textParameter" placeholder="Enter text" />
+      {/* optionally you can specify a className or wrapping tag, as well as placeholder text that an author will see in the visual editor when the value is empty */}
+      <UniformText parameterId="textParameter" as="h1" className="excellent" placeholder="Enter text" />
+    </div>
+  );
+}
+```
+
+##### Rich text parameters/fields
+
+For richText parameters, always use the `UniformRichText` component to automatically render the rich text (stored as Lexical JSON) to HTML:
+
+```tsx
+import { UniformRichText } from "@uniformdev/canvas-react";
+
+function Hero() {
+  return (
+    <div>
+      <UniformRichText parameterId="richTextParameter" placeholder="Prompt for author when value is empty" />
+    </div>
+  );
+}
+```
+
+##### Asset parameters/fields
+
+When rendering asset parameters, use the `flattenValues` helper to simplify value access:
+
+```tsx
+import { AssetParamValue, flattenValues } from "@uniformdev/canvas";
+
+interface MyComponentProps {
+  multipleImagesAssetParam: AssetParamValue;
+  singleImageAssetParam: AssetParamValue;
+}
+
+function MyComponent({
+  multipleImagesAssetParam,
+  singleImageAssetParam,
+}: MyComponentProps) {
+  // when multiple assets are allowed, flatten to an array
+  const images = flattenValues(multipleImagesAssetParam);
+  // when only one asset is allowed, flatten to a single object
+  const image = flattenValues(singleImageAssetParam, { toSingle: true });
+
+  return (
+    <>
+      {images?.map((img, index) => (
+        <img key={index} src={img?.url} width={img?.width} height={img?.height} />
+      ))}
+      <img src={image?.url} width={image?.width} height={image?.height} />
+    </>
+  );
+}
+```
+
+### Configuring Contextual Editing Live Preview
+
+To enable contextual editing and live preview to operate within the Uniform application, we need to register a _preview handler_ and _playground page_. The preview handler is an API endpoint that Uniform invokes when preview starts. It is responsible for mapping the composition ID under preview to a redirect to the correct frontend route to display that composition. The default handler does this using project map hierarchy.
+
+`pages/api/preview.ts`:
+
+```tsx
+import { createPreviewHandler } from "@uniformdev/canvas-next";
+
+const handler = createPreviewHandler({
+  // this is set in .env to an arbitrary value
+  secret: () => process.env.UNIFORM_PREVIEW_SECRET,
+  // optionally configure the playground route to enable previewing patterns
+  playgroundPath: "/playground",
+});
+
+export default handler;
+```
+
+The preview playground is a special route used to preview Uniform Patterns (reusable chunks of a page). The playground route includes the global page shell of the application:
+
+`pages/playground.tsx`:
+
+```tsx
+import { UniformPlayground } from "@uniformdev/canvas-react";
+
+export default function Playground() {
+  // wrap UniformPlayground in your page shell/styles to wrap the pattern previews with
+  return <UniformPlayground behaviorTracking="onLoad" />;
+}
+```
+
+## Configuring Personalization and A/B Testing (Uniform Context)
+
+### Required Context Packages
+
+The following npm packages must be installed to enable Uniform Context on Next Page Router:
+
+@uniformdev/context
+@uniformdev/context-next
+@uniformdev/context-react
+@uniformdev/cli
+
+### Pulling the Uniform Context Manifest
+
+Uniform Context relies on a static _manifest_ that defines user classification criteria and active test names. This manifest is downloaded using an API endpoint to a local file that is built into the application. The following package.json script can be used to invoke the manifest download:
+
+```json
+"uniform:pull:manifest": "uniform context manifest download --output ./src/uniform/contextManifest.json"
+```
+The "dev" and "build" npm scripts should run "uniform:pull:manifest" before beginning their regular tasks.
+
+### Enable Uniform Context SDK
+
+In order to initialize Uniform Context, we need to configure it and provide the manifest to it:
+
+`src/uniform/createUniformContext.ts`:
+
+```tsx
+import {
+  Context,
+  ManifestV2,
+  ContextPlugin,
+  enableDebugConsoleLogDrain,
+  enableContextDevTools
+} from "@uniformdev/context";
+import { NextCookieTransitionDataStore } from "@uniformdev/context-next";
+import { NextPageContext } from "next";
+import manifest from "./contextManifest.json";
+
+export function createUniformContext(
+  serverContext?: NextPageContext
+): Context {
+  const plugins: ContextPlugin[] = [
+    // optional, but smart defaults to help with debugging setup
+    enableContextDevTools(),
+    enableDebugConsoleLogDrain("debug"),
+  ];
+
+  const context = new Context({
+    // disables needing visitor consent before storing data (for testing)
+    defaultConsent: true,
+    manifest: manifest as ManifestV2,
+    transitionStore: new NextCookieTransitionDataStore({
+      serverContext,
+    }),
+    plugins,
+  });
+
+  return context;
+}
+```
+
+The context instance must then be provided to the `_app.tsx` so Uniform knows about it when rendering:
+
+`pages/_app.tsx`:
+```tsx
+import { UniformContext } from "@uniformdev/context-react";
+import { UniformAppProps } from "@uniformdev/context-next";
+import { createUniformContext } from "../uniform/createUniformContext";
+
+const clientContext = createUniformContext();
+
+function MyApp({
+  Component,
+  pageProps,
+  serverUniformContext,
+}: UniformAppProps) {
+  return (
+    <UniformContext
+      context={serverUniformContext ?? clientContext}
+      outputType={"standard"}
+    >
+      <Component {...pageProps} />
+    </UniformContext>
+  );
+}
+
+export default MyApp;
+```
+
+We must also configure the server-side Uniform Context instance when using server-side rendering:
+
+`pages/_document.tsx`:
+```tsx
+import { enableNextSsr } from "@uniformdev/context-next";
+import { createUniformContext } from "../uniform/uniformContext";
+
+  // required to enable SSR personalization
+  static async getInitialProps(
+    ctx: DocumentContext
+  ): Promise<DocumentInitialProps> {
+    const serverTracker = createUniformContext(ctx);
+    enableNextSsr(ctx, serverTracker);
+    return await Document.getInitialProps(ctx);
+  }
+```

package/references/uniform-react-next-app-router.mdc

@@ -0,0 +1,263 @@
+---
+description: 
+globs: 
+alwaysApply: false
+---
+# Uniform React Next App Router Developer Reference
+
+This document details how to use Uniform with React.js with Next App Router.
+
+@uniform.mdc describes general Uniform principles and practices.
+@uniform-sdk.mdc describes framework-agnostic developer principles.
+
+### Required npm packages
+
+The following npm packages must be installed to wire Uniform to Next App Router:
+
+@uniformdev/canvas-next-rsc
+@uniformdev/canvas
+
+### Fetching and rendering the composition
+
+In your dynamic route file (`app/[[...path]]/page.{tsx|jsx}`), it is necessary to fetch the Uniform composition instance for the current route.
+
+```tsx
+import {
+  UniformComposition,
+  PageParameters,
+  retrieveRoute,
+} from "@uniformdev/canvas-next-rsc";
+import { resolveComponent } from "@/uniform/resolve";
+
+export default async function Page(props: PageParameters) {
+  const route = await retrieveRoute(props);
+  return (
+    <>
+      <UniformComposition
+        {...props}
+        route={route}
+        resolveComponent={resolveComponent}
+        mode="server"
+      />
+    </>
+  );
+}
+```
+
+### Wrapping page in Uniform Context
+
+In order for personalization and A/B testing functionality to work client side, we must wrap the entire page in the UniformContext component. This should modify `app/layout.tsx` and wrap `{children}`.
+
+```tsx
+import { UniformContext } from "@uniformdev/canvas-next-rsc";
+
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html lang="en">
+      <body>
+        <main className="main">
+          <UniformContext>{children}</UniformContext>
+        </main>
+      </body>
+    </html>
+  );
+}
+```
+
+### Rendering Uniform Components using React Components
+
+The `UniformComposition` component needs to know how to map a Uniform Component instance's `type` to a React component that implements the UI for that component. This is done using resolveComponent. To use the component registry, first create a component:
+
+```tsx
+export const HeaderComponent = () => {
+  return <>Header</>;
+};
+```
+
+Then register it in the resolveComponent function:
+
+```tsx
+import {
+  DefaultNotImplementedComponent,
+  ResolveComponentFunction,
+  ResolveComponentResult,
+} from "@uniformdev/canvas-next-rsc/component";
+import { HeaderComponent } from "@/components/header";
+
+export const resolveComponent: ResolveComponentFunction = ({ component }) => {
+  let result: ResolveComponentResult = {
+    component: DefaultNotImplementedComponent,
+  };
+
+  if (component.type === "header") {
+    result = {
+      component: HeaderComponent,
+    };
+  }
+
+  return result;
+};
+```
+
+#### Mapping Uniform Components to React Components
+
+React components that receive Uniform Component data are passed props that correspond to the shape of the component definition they render. The `ComponentProps` type can be used to make the mapping explicit:
+
+```tsx
+import { ComponentProps } from "@uniformdev/canvas-next-rsc/component";
+import { RichTextParamValue } from "@uniformdev/canvas";
+
+type HeaderParameters = {
+  textParameter?: string;
+  richTextParameter?: RichTextParamValue;
+  // it is critical that all parameter props values are optional, because they can be undefined - even if 'required' on the component definition
+};
+
+type HeaderProps = ComponentProps<HeaderParameters>;
+
+export const HeaderComponent = ({ textParameter }: HeaderProps) => {
+  return (
+    <>
+      <span>{textParameter}</span>
+    </>
+  );
+};
+```
+
+#### Rendering child slots
+
+If a Uniform Component definition has slots defined, the components in those slots can be rendered using the `UniformSlot` component.
+
+```tsx
+import {
+  ComponentProps,
+  UniformSlot,
+} from "@uniformdev/canvas-next-rsc/component";
+import { RichTextParamValue } from "@uniformdev/canvas";
+
+type HeaderParameters = {
+  textParameter?: string;
+  richTextParameter?: RichTextParamValue;
+  // it is critical that all parameter props values are optional, because they can be undefined - even if 'required' on the component definition
+};
+type HeaderSlots = "logo" | "navigation";
+
+type HeaderProps = ComponentProps<HeaderParameters, HeaderSlots>;
+
+export const HeaderComponent = ({ slots, context, component }: HeaderProps) => {
+  return (
+    <>
+      <UniformSlot context={context} data={component} slot={slots.logo} />
+      <UniformSlot context={context} data={component} slot={slots.navigation} />
+    </>
+  );
+};
+```
+
+#### Rendering parameter values
+
+When rendering a `text` type parameter, using the `UniformText` component will enable authors to edit the value within the Uniform preview directly. Text parameters that do not have a visible component, such as alt text, should be rendered as their raw text value:
+
+```tsx
+import {
+  ComponentProps,
+  UniformText,
+} from "@uniformdev/canvas-next-rsc/component";
+import { RichTextParamValue } from "@uniformdev/canvas";
+
+type HeaderParameters = {
+  textParameter?: string;
+  richTextParameter?: RichTextParamValue;
+  // it is critical that all parameter props values are optional, because they can be undefined - even if 'required' on the component definition
+};
+
+type HeaderProps = ComponentProps<HeaderParameters>;
+
+export const HeaderComponent = ({ component, context }: HeaderProps) => {
+  return (
+    <>
+      <UniformText
+        component={component}
+        context={context}
+        parameterId="textParameter"
+        as="h1"
+      />
+    </>
+  );
+};
+```
+
+For rich text parameters, the `UniformRichText` component will automatically render the rich text stored as JSON to HTML:
+
+```tsx
+import {
+  ComponentProps,
+  UniformRichText,
+} from "@uniformdev/canvas-next-rsc/component";
+import { RichTextParamValue } from "@uniformdev/canvas";
+
+type HeaderParameters = {
+  textParameter?: string;
+  richTextParameter?: RichTextParamValue;
+  // it is critical that all parameter props values are optional, because they can be undefined - even if 'required' on the component definition
+};
+
+type HeaderProps = ComponentProps<HeaderParameters>;
+
+export const HeaderComponent = ({ component, context }: HeaderProps) => {
+  return (
+    <>
+      <UniformRichText
+        component={component}
+        context={context}
+        parameterId="richTextParameter"
+      />
+    </>
+  );
+};
+```
+
+Note: asset parameters are rendered directly from props, there is no `UniformAsset` component.
+
+### Configuring Contextual Editing Live Preview
+
+To enable contextual editing and live preview to operate within the Uniform application, we need to register a _preview handler_ and _playground page_. The preview handler is an API endpoint that Uniform invokes when preview starts. It is responsible for mapping the composition ID under preview to a redirect to the correct frontend route to display that composition. The default handler does this using project map hierarchy.
+
+`app/api/preview/route.ts`:
+
+```tsx
+import {
+  createPreviewGETRouteHandler,
+  createPreviewPOSTRouteHandler,
+  createPreviewOPTIONSRouteHandler,
+} from '@uniformdev/canvas-next-rsc/handler';
+
+export const GET = createPreviewGETRouteHandler({
+  playgroundPath: '/playground',
+  resolveFullPath: ({ path }) => (path ? path : '/playground'),
+});
+export const POST = createPreviewPOSTRouteHandler();
+export const OPTIONS = createPreviewOPTIONSRouteHandler();
+```
+
+The preview playground is a special route used to preview Uniform Patterns (reusable chunks of a page). It should use the same resolveComponent function. The playground route includes the global page shell of the application:
+
+`app/playground/page.tsx`:
+
+```tsx
+import {
+  UniformPlayground,
+  UniformPlaygroundProps,
+} from "@uniformdev/canvas-next-rsc";
+import { resolveComponent } from "@/uniform/resolve";
+
+export default function PlaygroundPage(props: {
+  searchParams: UniformPlaygroundProps["searchParams"];
+}) {
+  return <UniformPlayground {...props} resolveComponent={resolveComponent} />;
+}
+```

package/references/uniform-sdk.mdc

@@ -0,0 +1,97 @@
+---
+description:
+globs:
+alwaysApply: false
+---
+# Uniform SDK Developer Reference
+
+This document details general information and practices about how Uniform works for developers writing frontend applications.
+
+[uniform.mdc](mdc:.cursor/rules/uniform.mdc) describes general Uniform principles and practices.
+
+## Authenticating to Uniform
+
+To fetch a composition, you need a Uniform API key configured. API keys are commonly stored as `UNIFORM_API_KEY` in a `.env` file. They follow the format `uf......`. The API key requires "Read Published Compositions" permission.
+
+## How Uniform transfers layout data to frontend applications
+
+Uniform provides _composition instances_, a hierarchical JSON structure of components that define screens or pages in an application. A composition is made up of any number of _components_ which have a type that we map to a frontend component.
+
+### Routing
+
+Uniform's _Project Map_ feature enables automatic dynamic route delegation to Uniform authors. Frontend applications define a wildcard route that delegates routing to the Uniform _Route API_, which takes a dynamic path and resolves the correct composition instance data to display for that path.
+
+### Syncing data with the Uniform CLI
+
+Uniform provides a CLI which can be used to sync the state of a Uniform project, such as component definitions, pattern definitions, or compositions, to files on disk. These files may be committed to source control and used to ensure the states of environment or developer-specific projects are kept up to date to reduce the chance of errors.
+
+#### Required package for Uniform CLI
+
+The Uniform CLI is contained in the `@uniformdev/cli` npm package.
+
+#### Authenticating with the Uniform CLI
+
+The Uniform CLI requires a Uniform API key to authenticate. The API key and other connectivity details are stored in a `.env` file. When creating an API key for the CLI, the user can use the "Copy as .env" function in the Uniform dashboard to get the appropriate environment variable values.
+API keys used for the Uniform CLI require read and write permissions to any entity types that are to be synced. The default 'developer' role is a shortcut to full permissions.
+
+#### Configuring the Uniform CLI
+
+Uniform CLI is configured using the `uniform.config.{ts,js}` file in the root of a project. The file can be configured in two ways: to sync everything (choose this for initial setup), or to pick specific entity types to sync. Sync operates as a mirror by default, meaning creates, updates, and deletes are all synced.
+
+`uniform.config.ts` (sync all):
+
+```ts
+import { uniformConfig } from "@uniformdev/cli/config";
+
+export default uniformConfig({ preset: "all" });
+```
+
+`uniform.config.ts` (sync explicit types and customization options):
+
+```ts
+import { uniformConfig } from "@uniformdev/cli/config";
+
+export default uniformConfig({
+  // 'none' starts with no entities, and each entity type to sync is added explicitly
+  preset: "none",
+  config: {
+    serialization: {
+      // optionally override the default `./uniform-data` to store serialized files
+      directory: "./custom-path-to-serialized-files",
+      // optionally change the default yaml format to json
+      format: "json",
+      entitiesConfig: {
+        // specify entity types to sync. Each type can optionally override
+        // the defaults just for itself, i.e. directory, format
+        component: {},
+        componentPattern: { publish: true },
+      },
+    },
+  },
+});
+```
+
+#### Invoking the Uniform CLI
+
+The Uniform CLI operates using two primary commands:
+
+`uniform sync push` - takes the serialized state of entities (files on disk) and pushes that state into a Uniform project online.
+
+`uniform sync pull` - takes the online state of a Uniform project and pulls it into serialized files.
+
+Conventionally these commands are registered as package scripts to make it unnecessary to install the CLI package globally:
+
+`package.json`:
+
+```json
+{
+  "scripts": {
+    "uniform:pull": "uniform sync pull",
+    "uniform:push": "uniform sync push"
+  }
+}
+```
+
+#### Getting Uniform CLI help
+
+The Uniform CLI has a built-in help system. To get help on a command, run `uniform <command> --help`, for example `uniform sync pull --help`.

package/references/uniform.mdc

@@ -0,0 +1,153 @@
+---
+description: Uniform Content Modeling Reference - details content modeling options and techniques in Uniform CMS
+globs:
+alwaysApply: true
+---
+
+## Uniform Core Concepts
+
+Uniform is a modern, headless, component-based Content Management System (CMS). Its primary purpose is to allow non-technical authors (marketers, etc) to create and maintain websites and other similar experiences in a visual editor.
+
+### Uniform Compositions
+
+A composition instance in Uniform is roughly equivalent to a page. Composition definitions define a reusable schema for composition instances. Composition definitions have a structure identical to a Uniform Component, i.e. parameters and slots. Composition instances differ from components in that they also define a route or page. Instances of a composition create pages or routes within an application. The term "Composition" can be used to refer either to a definition or instance of a composition, you will need to infer which is meant (schema/reusable template = definition, page/route = instance).
+
+Composition parameters should only be used for global content that will never need to be personalized.
+Good example: OpenGraph data and meta tags (if they exist)
+Bad example: "hero title" belongs in a Hero component in the content slot.
+
+A single composition definition called 'Page' is generally a good starting point. Additional composition definitions are only required if the page shell is different (e.g. Page, Popup, Minimal Page), or if there are different parameters needed on the composition definition
+
+In developer terms, a composition instance is a dynamic layout that is defined by non-technical authors; a composition definition is a hierarchical content schema definition.
+
+### Uniform Components
+
+Uniform Components are used to allow CMS authors to create and manipulate visual elements on a composition. Each property of a Uniform Component, such as a title or image, is called a _Component Parameter_. See _Uniform Parameter/Field Types_ for the exact types of parameter that are allowed. Components have both a definition (their schema) and instances (when an instance of that schema is placed within a slot on a composition).
+
+Uniform Components can define named _slots_.
+
+- A slot allows additional components to be inserted within the Uniform Component. For example an accordion component could have an 'items' slot that allows adding Accordion Item components.
+- Each named slot has 0..n child components. The order in the slot determines the order of rendering.
+- Each slot definition allows only specific Uniform Components to be placed within it (by public id). It can also define the minimum and maximum number of components allowed.
+- Components allowed within slots can also have their own slots, with no depth limit - but it is generally undesirable to nest more than 2-3 levels deep to improve author understanding.
+- When a Uniform Composition is defined, it almost always has a generic 'content' slot added to it that allows using various components to define the layout.
+
+Uniform Component Definition attributes:
+
+- _name_
+- _public ID_
+- _parameters_
+- _slots_
+
+Uniform Slot Definition attributes:
+
+- _name_
+- _public ID_
+- _allowed components_
+- _min components_
+- _max components_
+
+In technical terms, a Uniform Component maps directly to a presentational frontend component such as a React component. The parameters are component props. Slots are component props that contain rendered child components.
+
+### Uniform Content Types
+
+Uniform Content Types define a reusable structure for individual reusable pieces of content. A Uniform content type differs from a Uniform component because a component represents a specific visual element on a composition/page, but a content type is an abstract, reusable content schema. An instance of a Uniform Content Type is called an _Entry_. Entries each have their own built-in slug: there is no need to define an explicit slug field.
+
+For example a Product might be a Uniform Content Type, and the data from instances of that Product could be presented in different contexts by Uniform Patterns such as Product List, Product Detail, or Product Card.
+
+Uniform Content Types define content properties called _Fields_ (e.g. a blog post could have a single-line text input for title, and a rich text editor for body). See _Uniform Parameter/Field Types_ for the exact types of field that are allowed.
+
+Uniform Content Type attributes:
+
+- _name_
+- _public ID_
+- _fields_
+
+### Uniform Patterns
+
+Patterns allow reusing the same content across compositions. The simplest way to think of a pattern is that it is a _shared component instance_ that can be placed within a slot to insert the pattern's content there. The pattern, like any other component instance, can have values in its parameters and child components in its slots. All usages of the same pattern reference the same shared content. Updates made to patterns are immediately reflected to all usages. Patterns may be nested within each other (e.g. a Blog Post Hero pattern could include a Author Bio pattern in one of its slots). Nesting beyond 2-3 levels can cause performance issues.
+
+#### Uniform Pattern Overrides
+
+Parameters on patterns can be defined _overridable_ by the pattern definition. Overridable parameter values default to using the value defined on the pattern, but consumers of the pattern may choose to break the inheritance of that parameter value and replace it with their own instance-specific value. Patterns that contain other patterns may not alter the overridability of nested pattern parameters: once overridable, any consumer of the pattern can change the value. Overrides are used to allow partial content sharing and exception cases.
+
+#### Using Uniform Patterns as Shared Content Snippets
+
+Patterns can be used to reuse shared content, for example the same legal disclaimer might be required on every press release. Both patterns and components allow content reuse: the difference is that patterns reuse exact content, whereas components reuse content schemas but do not provide content values.
+
+#### Using Uniform Patterns as Data Binding Templates
+
+Patterns can be used to create bindings between structured data (from Uniform Entries or external data sources, like REST APIs or other CMSes) and presentation parameters. A pattern can define a _Data Resource_ which is the result of fetching from a data source. Then parameters in the pattern can use _Dynamic Tokens_ to bind to elements within the data resource. For example, we might have a Card component that has a title and image. Then we create a Product Card pattern, based on the Card component, which has a Uniform Entry Data Resource that fetches an entry specified by the pattern consumer. The Product Card automatically binds the title and image from the product entry to the Card component's parameters. As an author, one can then insert a Product Card pattern, choose the product to use, and have the title and image automatically set up for them.
+
+Example of a resolved Data Resource (named 'myEntry'):
+{ "myEntry": { "fields": { "title": "hello world" } } }
+
+Example of a Dynamic Token in a text parameter referencing the myEntry title:
+"today's greeting: ${#jptr:/myEntry/fields/title}" (this resolves to "today's greeting: hello world")
+
+#### Uniform Pattern attributes
+
+- _name_
+- _type_ - public ID of the base Uniform Component
+- _public id_ - id of the pattern
+- _data resources_ (name, type)
+- _parameters_ (value, overridable)
+- _slots_
+
+## Conventions
+
+### Uniform Field/Parameter Types
+
+Uniform Fields or Uniform Parameters attributes:
+
+- _name_
+- _public ID_. Must be unique within a Uniform Component or Uniform Content Type (including the ID of group fields/parameters)
+- _localizable_. Localizable values have a distinct value for each locale; otherwise the value is the same for all locales.
+- _required_. Required means that a CMS author must input a value in order to be considered valid.
+- _type_. See list below.
+- _guidance_. Brief LLM instructions used when generating or editing values.
+- _overridable_. Only applies for fields/parameters on a pattern definition. Allows consumers of the pattern to break inheritance and change the pattern definition's value for the field/parameter.
+
+Exhaustive list of allowed field/parameter types:
+
+- _text_: Plain text content
+- _richText_: Formatted text with styling (Lexical JSON format)
+- _select_: Choose between a controlled vocabulary of options
+- _multi-select_: Choose between a controlled vocabulary of options, allowing multiple selections
+- _number_: Numeric value
+- _date_: Calendar date
+- _dateTime_: Date with timezone
+- _checkbox_: Boolean toggle
+- _link_: URL or internal reference
+- _asset_: Image, video, audio, or other file
+- _json_: A JSON object. Not for use in author-facing fields/parameters, who will have trouble editing JSON.
+- _contentReference_: References a single or multiple Entries of a specified type. Can only be used in Fields on Content Types (not Parameters on Components)
+- _enrichmentTag_: Tag content with enrichments (relevant segments) to make viewing the content alter the classification of the visitor that saw it.
+- _group_: Group multiple fields/parameters together visually, for example a group of address fields. IMPORTANT: fields added to a group must come directly after the group in the fields list.
+
+### Uniform Naming Conventions
+
+- All names should be title-cased prose, not technical shorthand (e.g. "Main Header" not "main-header" or "MainHeader"). There is no need to include the type of entity in a name (e.g. 'Hero' not 'Hero Component').
+- Do not name Uniform Components, Uniform Content Types, or Fields/Parameters based on visible content found in inputs; treat it as FPO (e.g. <h1>Hello</h1> does not mean name the component 'Hello' - describe its meaning instead, such as 'Headline').
+- _Public ID_ are developer-facing identifiers for Uniform entities. They are based on a slugified version of the name. Use a camel case, for example if the name is "Main Header", the public ID is "mainHeader". Public IDs must be unique within a given entity type (e.g. Uniform Components). You cannot alter public IDs after creating an entity.
+- Descriptions or help text should be no longer than 1 short sentence. It is not necessary to write help text unless we have specific expectations for authors. For example a 'Title' doesn't need help text. But if we identify an image that needs to be 250x250px, that expectation belongs in help text. Descriptions and help text are plain text, no markdown or HTML.
+
+## Tool Usage Tips
+
+- Before creating or updating Uniform Patterns, fetch Uniform Component Definitions to ensure you know about valid component types and parameters.
+- When making multiple updates to the same Uniform Pattern, such as adding a component and setting a parameter value, batch changes together into a single tool call to improve performance and consistency.
+- When a Uniform tool provides you with an edit URL offer it to the user as a link, unless you already have recently.
+- Before inserting, removing, or reordering parameters or fields from a Uniform Component or Uniform Content Type, make sure to fetch the latest definition data to ensure you target the correct location.
+- If you are tasked with reordering fields or parameters, you must remove them and re-add them in the new order
+
+## Unsupported Features
+
+The following Uniform features cannot currently be changed using MCP/AI. If asked to perform the following actions, explain you cannot yet do that, and when possible offer a link to perform the task in the Uniform web app.
+
+- Managing Uniform locales, both global registration and enablement on compositions or entries
+- Managing the project map, including adding or fetching nodes, or attaching compositions to project map nodes.
+- Managing compositions or entries (creating, updating)
+- Managing entry patterns
+- Managing block fields/parameters, or block type definitions
+- Setting the value of asset or reference type fields/parameters
+- Data sources, data types, and data resources