@dextinity/agent-features 2.0.0-canary-20260806092023 → 10.0.0-beta.0

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@dextinity/agent-features",
-  "version": "2.0.0-canary-20260806092023",
+  "version": "10.0.0-beta.0",
   "description": "Agent features (skills and rules) for Dextinity projects",
   "repository": {
     "directory": "packages/agent-features",
     "type": "git",
-    "url": "https://github.com/vivid-planet/comet"
+    "url": "https://github.com/vivid-planet/dextinity"
   },
   "license": "BSD-2-Clause",
   "files": [

package/skills/dev-pm/SKILL.md

@@ -5,7 +5,7 @@ description: Run, restart, stop, and inspect logs/status of long-running develop
 
 # dev-pm Skill
 
-`dev-pm` (`@comet/dev-process-manager`) supervises long-running dev processes (servers, watchers, codegen, storybook, docker, …). Available scripts and groups are defined in `dev-pm.config.ts` at the repo root — read it to discover what can be started.
+`dev-pm` (`dev-process-manager`) supervises long-running dev processes (servers, watchers, codegen, storybook, docker, …). Available scripts and groups are defined in `dev-pm.config.ts` at the repo root — read it to discover what can be started.
 
 ## Critical rules
 

package/skills/dextinity-admin-ui/SKILL.md

@@ -29,10 +29,11 @@ after the system genuinely can't express what you need.
 3. **Consistency.** Every screen built from the same components and tokens looks and behaves the
    same way.
 
-This holds **even when a project's design deliberately differs** from the current library
-defaults: prefer the Dextinity component or token, and apply that project-specific difference by
-configuring the theme — not by re-styling individual components. Add custom styling only when
-explicitly instructed, or when no component, prop, or token can produce the result.
+This holds **even when a project's design deliberately differs** from the current library defaults —
+a permanent design decision, not a gap a later library upgrade will close. Prefer the Dextinity component
+or token, and apply that project-specific difference by configuring the theme — not by re-styling
+individual components. Add custom styling only when explicitly instructed, or when no component, prop,
+or token can produce the result.
 
 ## Decision framework
 
@@ -291,7 +292,7 @@ Don't use `Grid` or `Stack` to lay out form fields: Dextinity stacks them vertic
 grouped with `FieldSet` or `FormSection`.
 
 `sx` is fine for an occasional layout property that no `Stack` or `Grid` prop covers, such as
-`flexGrow`. It is not for visual styling — that goes through `styled()`.
+`flexGrow`. On your own markup, it is not for visual styling — that goes through `styled()`.
 
 ### Page structure: `MainContent`, `Toolbar`, and their parts
 
@@ -490,3 +491,54 @@ import { Delete } from "@dextinity/admin-icons";
 
 <Delete fontSize="small" color="error" />;
 ```
+
+## Customizing an existing Dextinity Admin component
+
+When a Dextinity Admin component needs to look or behave differently than its defaults, customize it
+through the mechanisms it already supports: the component's own props, a per-slot `slotProps` prop,
+and theme-level `styleOverrides` and `defaultProps`. A _slot_ is a named inner element of a component;
+only `root` is universal — a component lists its own slot names on its props type. Which mechanism you
+pick depends on whether you're changing behavior or appearance.
+
+### Behavior
+
+Start with the component's own props. To reach an inner element, use `slotProps`: it forwards props
+to a named slot, letting you override that slot's props. This configures the component rather than
+restyling it.
+
+```tsx
+// Override an inner slot's props — here, disable the button behind the content
+<ContentOverflow slotProps={{ clickableContent: { disabled: true } }}>{children}</ContentOverflow>
+```
+
+### Appearance
+
+To change how a Dextinity component looks, configure the theme rather than the component itself — the core
+principle's rule for a project-specific design difference. `createDextinityTheme`'s `components` map takes
+a `DextinityAdmin*` key (MUI components use their `Mui*` key); `styleOverrides` restyles a component's
+slots and `defaultProps` sets default prop values, such as swapping an icon through `iconMapping`.
+Both apply to every instance, so the deviation stays consistent and is defined in one reviewable place.
+
+Styling a single instance directly is the rare exception — for a change genuinely specific to that
+instance, or when you're explicitly told to. Which tool you use is then the same as anywhere else:
+`sx` (or `slotProps.<slot>.sx` for a slot) for small layout, `styled()` for other custom styling, per
+the styling section above. Use this only for a true single-instance change; a difference that recurs
+belongs in the theme, not repeated on each instance.
+
+```tsx
+// Avoid — a styled() wrapper for a design difference that belongs in the theme
+const HighlightedContentOverflow = styled(ContentOverflow)`
+    background-color: ${({ theme }) => theme.palette.grey[50]};
+`;
+
+// Prefer — configure the theme, applied to every instance
+const theme = createDextinityTheme({
+    components: {
+        DextinityAdminContentOverflow: {
+            styleOverrides: {
+                root: ({ theme }) => ({ backgroundColor: theme.palette.grey[50] }),
+            },
+        },
+    },
+});
+```

package/skills/dextinity-mail-react/SKILL.md

@@ -41,7 +41,7 @@ This applies to seemingly simple things: `border-radius`, `background-image`, `f
 
 ### Library Documentation
 
-Full documentation for `@dextinity/mail-react`: https://docs.comet-dxp.com/docs/features-modules/building-html-emails/
+Full documentation for `@dextinity/mail-react`: https://cms-docs.dextinity.com/docs/features-modules/building-html-emails/
 
 ---
 
@@ -125,6 +125,24 @@ Always use `theme.breakpoints.*.belowMediaQuery` inside `registerStyles` instead
 
 ## Common Pitfalls
 
+### Start Raw Content Inside a Column With `<tr>`
+
+`mj-column` wraps every child in its own `<tr><td>` — except `MjmlRaw` content, which goes straight into the column's table unwrapped. A `<table>`, `<div>`, or `<img>` in that position ends up outside the column's table instead, and MJML reports no error. This covers the `Html*` components. Open with a `<tr>` and put the markup in a `<td>`:
+
+```tsx
+<MjmlColumn>
+    <MjmlRaw>
+        <tr>
+            <td>{/* your raw markup */}</td>
+        </tr>
+    </MjmlRaw>
+</MjmlColumn>
+```
+
+`HtmlText` is the exception: it renders the `<td>` itself, so a surrounding `<tr>` is all it needs — unless its `element` prop renders something else, which needs a `<td>` again.
+
+`MjmlColumn` and `MjmlHero` are both affected — `MjmlSection` and `MjmlWrapper` already place their children inside a shared cell, so any root element is safe there. `MjmlDivider` supplies both the row and the cell; use it instead of a hand-wrapped `HtmlDivider` whenever you are in an `MjmlColumn`.
+
 ### Avoid Block-Level HTML Elements Inside Ending Tags
 
 Don't use `<p>`, `<h1>`, `<h2>`, or other block-level HTML elements inside ending tags. They have wildly inconsistent default margins and spacing across email clients and add no rendering value in email HTML. Instead, use `<td>`, `<div>`, and `<span>` for structure, and build your typography hierarchy through `MjmlText`/`HtmlText` variants rather than HTML semantics. If a block-level element is truly unavoidable, always reset its margins inline: `style={{ margin: 0 }}`.
@@ -303,6 +321,8 @@ All components are imported from `@dextinity/mail-react` — never from `@faire/
 | `MjmlPixelImageBlock` | re-exported `MjmlImage` | an `MjmlColumn` (standard MJML layout)         |
 | `HtmlPixelImageBlock` | raw `<img>`             | raw HTML or MJML ending tags such as `MjmlRaw` |
 
+Inside `MjmlRaw` in an `MjmlColumn`, `HtmlPixelImageBlock` needs its own `<tr>` and `<td>` — see _Start Raw Content Inside a Column With `<tr>`_ above.
+
 ```tsx
 <MjmlSection indent>
     <MjmlColumn>
@@ -361,6 +381,8 @@ export const { MjmlRichTextBlock, HtmlRichTextBlock } = createRichTextBlock({
 | `MjmlRichTextBlock` | `MjmlText`                  | an `MjmlColumn` (standard MJML layout)         |
 | `HtmlRichTextBlock` | `HtmlText` (`<div>`)        | raw HTML or MJML ending tags such as `MjmlRaw` |
 
+Inside `MjmlRaw` in an `MjmlColumn`, `HtmlRichTextBlock` needs its own `<tr>` and `<td>` — see _Start Raw Content Inside a Column With `<tr>`_ above.
+
 Usage sites pass only `data`:
 
 ```tsx
@@ -392,6 +414,8 @@ Key behaviors:
     );
     ```
 
+    For a list block type, target `.<className> .richTextBlock__listItemText` instead of `> div` — the list's cells carry their own font styles, which outrank a rule on the block's element.
+
 - **Multiple configurations per app.** Each factory call is independent — rename the destructured components per use case:
 
     ```tsx
@@ -426,9 +450,11 @@ Key behaviors:
     });
     ```
 
-- **Lists** render flat (`<ul>` / `<ol>` inside one text component per list); nesting by draft depth isn't supported.
+- **Lists** render as a table inside one text component, with a row per item, a marker cell and a text cell — the indent and the marker gap are cell padding, which is the only spacing Outlook on Windows applies reliably.
+- **List spacing** comes from the theme's `list.indent` (before the marker), `list.markerGap` (between the marker and the text) and `list.itemSpacing` (between items), all responsive and all applying to every list the block renders. To override it, register a rule scoped to a list's type or variant modifier with `{ inline: true }`, which has MJML write the declaration into the cell's `style` attribute at compile time so it also reaches Outlook.
+- **List markers** come from the theme's `list.unorderedMarker` and `list.orderedMarker`, each either a fixed node (`unorderedMarker: "▪"`) or a function of the item's `index` and its list's `depth`.
 - Spacing between blocks comes from the theme's `bottomSpacing` (the last block gets none); headings are styled text, not semantic `<h1>` elements.
-- Rendered elements carry `richTextBlock__text`, `richTextBlock__list`, `richTextBlock__listItem`, and `richTextBlock__link` class names for targeting with `registerStyles`.
+- Rendered elements carry `richTextBlock__text`, `richTextBlock__list`, `richTextBlock__listItem`, `richTextBlock__listItemMarker`, `richTextBlock__listItemText`, and `richTextBlock__link` class names for targeting with `registerStyles`. The list table also carries `richTextBlock__list--ordered` or `richTextBlock__list--unordered`, plus a modifier naming the text variant its items render with, such as `richTextBlock__list--variantBody`. Its rows carry `richTextBlock__listItem--itemSpacing`, or `richTextBlock__listItem--blockSpacing` on the last row when spacing follows the list. Its cells restate the text styles inline, so a rule targeting list text needs `!important`.
 
 ---
 
@@ -617,5 +643,5 @@ Storybook previews show how the email renders in a web browser, but email client
 
 The `@dextinity/mail-react` package focuses on building email markup. For sending emails and managing templates in a Dextinity project:
 
-- **Mail Templates Module** — server-side template registration, dependency injection, and sending. Integrates with `@dextinity/mail-react` via `renderMailHtml`. Docs: https://docs.comet-dxp.com/docs/features-modules/mail-templates-module/
-- **Mailer Module** — lower-level mail sending service. Docs: https://docs.comet-dxp.com/docs/features-modules/mailer-module/
+- **Mail Templates Module** — server-side template registration, dependency injection, and sending. Integrates with `@dextinity/mail-react` via `renderMailHtml`. Docs: https://cms-docs.dextinity.com/docs/features-modules/mail-templates-module/
+- **Mailer Module** — lower-level mail sending service. Docs: https://cms-docs.dextinity.com/docs/features-modules/mailer-module/

package/skills/dextinity-mail-react/references/components-and-theme.md

@@ -43,11 +43,28 @@ const theme = createTheme({
     sizes: {
         contentIndentation: { default: 40, tablet: 30, mobile: 20 },
     },
+    list: {
+        indent: { default: 24, tablet: 16, mobile: 8 },
+    },
 });
 ```
 
 The `default` key provides the base value (rendered inline). Other keys generate media query overrides automatically.
 
+### List Markers
+
+`list.unorderedMarker` and `list.orderedMarker` set the markers of the lists the RichText block renders: a fixed node, or a function receiving the item's zero-based `index` and the `depth` of its list. Use plain HTML and React elements, not MJML components:
+
+```tsx
+const theme = createTheme({
+    list: {
+        unorderedMarker: ({ depth }) => ["▪", "–", "·"][depth % 3],
+        // 97 is the code of "a", so nested items are lettered a., b., c.
+        orderedMarker: ({ index, depth }) => (depth === 0 ? `${index + 1}.` : `${String.fromCharCode(97 + index)}.`),
+    },
+});
+```
+
 ---
 
 ## Module Augmentation Interfaces
@@ -279,13 +296,13 @@ Themed text for use inside ending tags (`MjmlText`, `MjmlRaw`) or custom HTML st
 **CSS classes:** `.htmlText`, `.htmlText--{variant}`, `.htmlText--bottomSpacing`.
 
 ```tsx
-<MjmlRaw>
-    <table>
+<MjmlColumn>
+    <MjmlRaw>
         <tr>
-            <HtmlText variant="body">Themed text inside a raw table</HtmlText>
+            <HtmlText variant="body">Themed text in a row of the column's table</HtmlText>
         </tr>
-    </table>
-</MjmlRaw>
+    </MjmlRaw>
+</MjmlColumn>
 
 <MjmlText>
     <HtmlText element="div" variant="caption">Rendered as a div</HtmlText>

package/skills/dextinity-major-migration/SKILL.md

@@ -14,10 +14,10 @@ Do NOT use for minor or patch upgrades, or for ongoing feature work on a project
 ## Locate the migration guide
 
 1. **Find out the target major** from the user if not specified.
-2. **Browse the index:** https://github.com/vivid-planet/comet/tree/main/docs/docs/7-migration-guide — use a GitHub MCP tool if available, otherwise `WebFetch`.
+2. **Browse the index:** https://github.com/vivid-planet/dextinity/tree/main/docs/docs/7-migration-guide — use a GitHub MCP tool if available, otherwise `WebFetch`.
 3. **Download the raw Markdown** so all content is in context:
     ```
-    https://raw.githubusercontent.com/vivid-planet/comet/refs/heads/main/docs/docs/7-migration-guide/migration-from-v{N}-to-v{N+1}.md
+    https://raw.githubusercontent.com/vivid-planet/dextinity/refs/heads/main/docs/docs/7-migration-guide/migration-from-v{N}-to-v{N+1}.md
     ```
 4. **If no guide exists** for the target version, stop and tell the user. Don't migrate without an official guide.
 
@@ -73,7 +73,7 @@ Record the resolved site list durably (e.g. a note on the first `TaskCreate` tas
 
 If a step is ambiguous or doesn't match the project, consult before guessing:
 
-- **https://github.com/vivid-planet/comet** — the monorepo. Check the source of the package the guide discusses for the new public API shape.
+- **https://github.com/vivid-planet/dextinity** — the monorepo. Check the source of the package the guide discusses for the new public API shape.
 - **https://github.com/vivid-planet/comet-starter** — the canonical reference project, always kept on the current major. Use it for questions like "how should `tsconfig.json` look after this migration?"
 
 Prefer the GitHub MCP; fall back to `WebFetch` on `raw.githubusercontent.com`. If still unclear, ask the user — don't guess.

package/skills/dextinity-minor-update/SKILL.md

@@ -16,7 +16,7 @@ Two rules hold across every `@dextinity/*` core package in the project, before a
 - **Pinned versions only.** Every core `@dextinity/*` entry must be an exact version (e.g. `8.21.0`), never a range (`^8.21.0`, `~8.21.0`, `>=…`). If you see a caret or tilde on a core package, the project is in a broken state — stop and tell the user.
 - **All core packages on the same version.** Every core `@dextinity/*` package in the project must be pinned to the same version across every `package.json`. There is no supported mix-and-match.
 
-These rules apply only to the core set (packages released together from the Dextinity monorepo). Satellite packages like `@comet/dev-process-manager` are out of scope — see Step 1.
+These rules apply only to the core set (packages released together from the Dextinity monorepo). Any other `@dextinity/*` package a project happens to depend on is out of scope — see Step 1.
 
 ## When to use
 
@@ -60,8 +60,8 @@ grep -n '"@dextinity/' package.json api/package.json admin/package.json \
 
 Notes:
 
-- Not every `@dextinity/*` package follows the core release cadence. Packages that live outside the core monorepo (for example `@comet/dev-process-manager`) may use a different versioning scheme (often `^x.y.z`). **Only** bump packages whose current version matches the core Dextinity version (the one shared by `@dextinity/cms-api`, `@dextinity/admin`, `@dextinity/site-nextjs`, etc.). Leave the others untouched.
-- Use the invariants to tell core from satellite: core packages are all pinned to the same exact version, with no caret or tilde. Anything with a range or a different version is not core — verify before touching it.
+- Not every `@dextinity/*` dependency you find follows the core release cadence. **Only** bump packages whose current version matches the core Dextinity version (the one shared by `@dextinity/cms-api`, `@dextinity/admin`, `@dextinity/site-nextjs`, etc.). Leave the others untouched.
+- Use the invariants to tell core from non-core: core packages are all pinned to the same exact version, with no caret or tilde. Anything with a range or a different version is not core — verify before touching it.
 - If you find core packages on different versions, or any core package using a range (`^`, `~`), the project violates the invariants. Stop and tell the user — don't paper over it by bumping.
 
 Confirm the **current major** from the version string (e.g. `8.20.4` → major `8`).
@@ -100,7 +100,7 @@ grep -n '<OLD_VERSION>' package.json api/package.json admin/package.json \
 
 If every match is a `@dextinity/*` line, you can safely edit each file. If there are non-`@dextinity` matches, edit the `@dextinity` lines individually.
 
-**Do not touch** packages like `@comet/dev-process-manager` that don't share the core version — see Step 1.
+**Do not touch** `@dextinity/*` packages that don't share the core version — see Step 1.
 
 ---
 
@@ -181,11 +181,11 @@ Tell the user:
 
 ## Common pitfalls
 
-| Pitfall                                                       | How to avoid                                                                                        |
-| ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
-| Picking a canary/beta as "newest"                             | Filter out any version containing `-` in Step 2.                                                    |
-| Bumping `@comet/dev-process-manager` (or similar) by accident | Only bump packages pinned to the shared core version — see Step 1.                                  |
-| Forgetting the root `package.json`                            | The repo root has its own `package.json` with `@dextinity/cli`. Always include it in the grep.      |
-| Assuming "up to date" means the install did nothing           | It means the lockfile already satisfies the new range. Verify with `grep` against the lockfile.     |
-| Running installs in parallel in a sandbox                     | If `&` backgrounding fails, just run the installs sequentially. Takes a bit longer, works reliably. |
-| Crossing a major version                                      | This skill is minor/patch only. Stop and warn the user.                                             |
+| Pitfall                                               | How to avoid                                                                                        |
+| ----------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| Picking a canary/beta as "newest"                     | Filter out any version containing `-` in Step 2.                                                    |
+| Bumping a non-core `@dextinity/*` package by accident | Only bump packages pinned to the shared core version — see Step 1.                                  |
+| Forgetting the root `package.json`                    | The repo root has its own `package.json` with `@dextinity/cli`. Always include it in the grep.      |
+| Assuming "up to date" means the install did nothing   | It means the lockfile already satisfies the new range. Verify with `grep` against the lockfile.     |
+| Running installs in parallel in a sandbox             | If `&` backgrounding fails, just run the installs sequentially. Takes a bit longer, works reliably. |
+| Crossing a major version                              | This skill is minor/patch only. Stop and warn the user.                                             |