@ixo/editor 6.1.0 → 6.1.2

package/README.md

@@ -1,433 +1,313 @@
-# IXO Editor
+# @ixo/editor
 
-A custom BlockNote editor wrapper built specifically for the IXO team's needs. This package provides a highly customized rich text editing experience built on top of [BlockNote](https://www.blocknotejs.org/) with support for both **Shadcn UI** and **Mantine UI**.
+A collaborative, **workflow** editor for the IXO ecosystem, built on [BlockNote](https://www.blocknotejs.org/). Beyond rich text, `@ixo/editor` turns a document into a runnable flow: blocks carry configuration, conditional logic, and executable **actions**, execution is gated by a **flow engine** and authorized with **UCAN** capabilities, and every change is synchronized in real time across collaborators over the Matrix protocol via Yjs CRDTs.
 
-> **Note**: This package is designed for internal IXO team use and is not intended for public consumption, though it is hosted publicly.
+> **Internal package.** Maintained for IXO products (primarily [impacts-x-web](https://github.com/ixoworld)). It is published publicly but is not intended as a general-purpose editor. The public API changes with product needs.
+
+---
+
+## What it is
+
+The editor operates in two modes, selected by a document's `docType`:
+
+- **Template mode** (`docType: 'template'`) — design time. Authors configure reusable workflow blocks: properties, conditional logic, dependencies, and which actor may execute what.
+- **Flow mode** (`docType: 'flow'`, the default) — run time. Participants execute the configured workflow. Conditions are evaluated live, blocks show/hide/enable accordingly, actions run through the flow engine, and per-block runtime state syncs to every collaborator.
+
+Under the hood it combines:
+
+- **BlockNote 0.29** + a custom IXO block schema (checkbox, form, list, proposal, claim, bid, action, notify, domain, …).
+- **Yjs CRDTs over Matrix** (`@ixo/matrix-crdt`) for conflict-free, multi-user, persistent state — no separate database required.
+- A **flow engine** that runs blocks through an activation → authorization → invocation → action → storage pipeline.
+- An **action registry** of pluggable action types (`qi/<namespace>.<verb>`) that the generic `action` block dispatches to.
+- **UCAN** delegations and invocations for cryptographic, per-block execution authorization.
+- A **flow compiler** that reads/writes a portable "Base UCAN" flow representation, and a **flow agent** runtime for automated flow progression.
+
+For the full picture, start with [`docs/architecture/architecture-overview.md`](docs/architecture/architecture-overview.md) and the plain-language [`docs/authorization/flows-actions-ucans-explained.md`](docs/authorization/flows-actions-ucans-explained.md).
 
 ## Features
 
-- 🎨 **Multi-UI Support**: Choose between Shadcn UI or Mantine UI components.
-- 🔧 **Simplified API**: Wrapped BlockNote functionality with sensible defaults
-- 📝 **Rich Text Editing**: Full support for headings, lists, code blocks, tables, and more
-- 🔗 **Custom Blocks**: Built-in custom blocks including dynamic List block for DID data
-- 🖼️ **Media Support**: Image and file upload handling
-- 🎯 **TypeScript**: Full TypeScript support with exported types
-- 🤝 **Collaboration Ready**: Built-in Matrix-based collaborative editing with real-time synchronization
-- 📱 **Responsive**: Mobile-friendly editor experience
-- 💎 **Complete CSS Bundles**: Self-contained CSS with all dependencies included
+- 🧩 **Workflow blocks** — checkboxes, forms, lists, proposals, claims, bids, API requests, notifications, domain/entity actions, and a generic `action` block.
+- 🔀 **Template vs flow modes** — design reusable workflows, then execute them.
+- 🤝 **Real-time collaboration** — Matrix + Yjs CRDTs; state is collaborative and persistent by default.
+- ⚙️ **Flow engine** — declarative activation conditions, actor authorization, and per-block runtime state.
+- 🔐 **UCAN authorization** — flow owners delegate execution capabilities; invocations provide an auditable trail.
+- 🧠 **Action registry** — add new action types declaratively; the host app supplies the side-effecting handlers.
+- 🖥️ **Server-friendly core** — `@ixo/editor/core` exposes the flow engine, action registry, UCAN, and flow agent with no React/Mantine/BlockNote UI dependencies.
+- 🎨 **Mantine UI** — themable light/dark, self-contained CSS bundles.
+- 🎯 **TypeScript-first** — augmented editor types and exported prop schemas.
 
-## Installations
+## Installation
 
 ```bash
-npm install @ixo/editor
-# or
-yarn add @ixo/editor
-# or
 pnpm add @ixo/editor
+# or: npm install @ixo/editor / yarn add @ixo/editor
 ```
 
-## Quick Start
+### Peer dependencies
 
-### Shadcn UI Version (Default)
+| Package                                             | Version    | Needed for                     |
+| --------------------------------------------------- | ---------- | ------------------------------ |
+| `react`, `react-dom`                                | `^18.0.0`  | Everything                     |
+| `@mantine/core`, `@mantine/hooks`, `@mantine/dates` | `^7.11.2`  | The editor UI                  |
+| `@ixo/matrix-crdt`                                  | `*`        | Collaborative editing          |
+| `@ixo/surveys`                                      | `^0.1.0`   | Form / survey blocks           |
+| `matrix-js-sdk`                                     | `>=37.5.0` | Collaborative editing (Matrix) |
 
-```tsx
-import React from 'react';
-import { useCreateIxoEditor, IxoEditor } from '@ixo/editor/shadcn';
-import '@ixo/editor/style-shadcn.css'; // Complete CSS bundle - no other imports needed!
+> **v6 is Mantine-only.** The Shadcn UI variant that shipped in v2 has been removed. See [Migration](#migration).
 
-function MyEditor() {
-  const editor = useCreateIxoEditor({
-    theme: 'light',
-    initialContent: [
-      {
-        type: 'heading',
-        content: 'Welcome to IXO Editor',
-        props: { level: 1 },
-      },
-      {
-        type: 'paragraph',
-        content: 'Start typing to create amazing content!',
-      },
-    ],
-  });
+## Package entry points
 
-  return <IxoEditor editor={editor} onChange={() => console.log('Content changed')} />;
-}
-```
+| Import                | Contents                                                                                                                       |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `@ixo/editor`         | Default entry — the Mantine editor plus the full public API (hooks, components, flow engine, UCAN, flow compiler, flow agent). |
+| `@ixo/editor/mantine` | Explicit Mantine entry (same UI surface).                                                                                      |
+| `@ixo/editor/core`    | **UI-free** flow engine, action registry, UCAN, flow compiler, and flow agent. Safe for Node/server consumers (e.g. oracles).  |
+
+### CSS bundles
 
-### Mantine UI Version
+| Stylesheet                      | Contents                                                       |
+| ------------------------------- | -------------------------------------------------------------- |
+| `@ixo/editor/style.css`         | Complete bundle: Inter fonts + Mantine + IXO styles (default). |
+| `@ixo/editor/style-mantine.css` | Same as `style.css`.                                           |
+| `@ixo/editor/style-scoped.css`  | Scoped variant to reduce global bleed.                         |
+| `@ixo/editor/style-core.css`    | IXO custom styles only (advanced/bring-your-own base).         |
+
+## Quick start (standalone)
+
+A non-collaborative, single-user editor:
 
 ```tsx
-import React from 'react';
 import { MantineProvider } from '@mantine/core';
-import { useCreateIxoEditor, IxoEditor } from '@ixo/editor/mantine';
-import '@ixo/editor/style-mantine.css'; // Complete CSS bundle - no other imports needed!
+import { useCreateIxoEditor, IxoEditor } from '@ixo/editor';
+import '@ixo/editor/style.css';
 
 function MyEditor() {
   const editor = useCreateIxoEditor({
     theme: 'light',
     initialContent: [
-      {
-        type: 'heading',
-        content: 'Welcome to IXO Editor',
-        props: { level: 1 },
-      },
+      { type: 'heading', content: 'Welcome to the IXO Editor', props: { level: 1 } },
+      { type: 'paragraph', content: 'Type “/” to insert a block.' },
     ],
   });
 
   return (
     <MantineProvider>
-      <IxoEditor editor={editor} onChange={() => console.log('Content changed')} />
+      <IxoEditor editor={editor} onChange={() => console.log('changed')} />
     </MantineProvider>
   );
 }
 ```
 
-## Import Options
-
-The package provides flexible import patterns to suit your needs:
-
-### Option 1: UI-Specific Imports (Recommended)
-
-```tsx
-// Shadcn version with complete CSS bundle
-import { IxoEditor, useCreateIxoEditor } from '@ixo/editor/shadcn';
-import '@ixo/editor/style-shadcn.css';
-
-// Mantine version with complete CSS bundle
-import { IxoEditor, useCreateIxoEditor } from '@ixo/editor/mantine';
-import '@ixo/editor/style-mantine.css';
-```
+## Collaborative editing
 
-### Option 2: Default Import (Shadcn)
+Real-time, multi-user editing backed by a Matrix room. `useCreateCollaborativeIxoEditor` builds the Y.Doc, wires the `MatrixProvider`, and returns the editor alongside the live CRDT handles.
 
 ```tsx
-// Uses Shadcn version by default for backward compatibility
-import { IxoEditor, useCreateIxoEditor } from '@ixo/editor';
+import { MantineProvider } from '@mantine/core';
+import { useCreateCollaborativeIxoEditor, IxoEditor } from '@ixo/editor';
 import '@ixo/editor/style.css';
-```
-
-### CSS Bundle Options
-
-- `@ixo/editor/style-shadcn.css` - Complete bundle: Inter fonts + Shadcn + IXO styles
-- `@ixo/editor/style-mantine.css` - Complete bundle: Inter fonts + Mantine + IXO styles
-- `@ixo/editor/style.css` - Default bundle (same as shadcn)
-- `@ixo/editor/style-core.css` - Only IXO custom styles (for advanced users)
-
-## API Reference
-
-### `useCreateIxoEditor`
-
-The main hook for creating an IXO editor instance. Available in both UI versions.
-
-```tsx
-const editor = useCreateIxoEditor(options?: IxoEditorOptions);
-```
-
-#### Options
-
-| Option              | Type                              | Default            | Description                               |
-| ------------------- | --------------------------------- | ------------------ | ----------------------------------------- |
-| `theme`             | `'light' \| 'dark'`               | `'light'`          | Editor color theme                        |
-| `uploadFile`        | `(file: File) => Promise<string>` | Data URL converter | File upload handler                       |
-| `initialContent`    | `PartialBlock[]`                  | `undefined`        | Initial editor content                    |
-| `editable`          | `boolean`                         | `true`             | Whether editor is editable                |
-| `sideMenu`          | `boolean`                         | `true`             | Show side menu (drag handle, plus button) |
-| `slashMenu`         | `boolean`                         | `true`             | Enable slash commands menu                |
-| `formattingToolbar` | `boolean`                         | `true`             | Show formatting toolbar                   |
-| `linkToolbar`       | `boolean`                         | `true`             | Show link toolbar                         |
-| `filePanel`         | `boolean`                         | `true`             | Show file panel                           |
-| `tableHandles`      | `boolean`                         | `true`             | Show table manipulation handles           |
-
-### `IxoEditor` Component
-
-The main editor component. Available in both UI versions with identical APIs.
-
-```tsx
-<IxoEditor editor={editor} className="my-custom-class" onChange={() => {}} onSelectionChange={() => {}} />
-```
-
-#### Props
-
-| Prop                | Type                           | Description                               |
-| ------------------- | ------------------------------ | ----------------------------------------- |
-| `editor`            | `BlockNoteEditor \| undefined` | Editor instance from `useCreateIxoEditor` |
-| `className`         | `string`                       | Additional CSS classes                    |
-| `onChange`          | `() => void`                   | Callback when content changes             |
-| `onSelectionChange` | `() => void`                   | Callback when selection changes           |
-| `children`          | `React.ReactNode`              | Custom child components                   |
-
-## Advanced Usage
-
-### Custom File Upload
-
-```tsx
-const editor = useCreateIxoEditor({
-  uploadFile: async (file: File) => {
-    const formData = new FormData();
-    formData.append('file', file);
-
-    const response = await fetch('/api/upload', {
-      method: 'POST',
-      body: formData,
-    });
-
-    const { url } = await response.json();
-    return url;
-  },
-});
-```
-
-### Collaborative Editing
-
-For real-time collaborative editing, use the `useCreateCollaborativeIxoEditor` hook with Matrix protocol:
 
-```tsx
-import { useCreateCollaborativeIxoEditor, IxoEditor } from '@ixo/editor/shadcn';
-
-function CollaborativeEditor() {
-  const { editor, connectionStatus } = useCreateCollaborativeIxoEditor({
+function CollaborativeEditor({ matrixClient }) {
+  const { editor, connectionStatus, connectedUsers, awarenessInstance } = useCreateCollaborativeIxoEditor({
     theme: 'light',
+    roomId: '!roomId:matrix.org',
+    matrixClient,
+    permissions: { write: true },
     user: {
-      id: 'user-123',
-      name: 'John Doe',
+      id: '@did-ixo-ixo1abc:server', // Matrix user ID
+      name: 'Jane Doe',
       color: '#FF5733',
-      accessToken: 'your-matrix-access-token',
-      address: 'your-user-address',
+      accessToken: 'matrix-access-token',
+      address: 'ixo1abc…', // bech32 address
+      did: 'did:ixo:ixo1abc…', // full DID, required for UCAN signing
     },
-    matrixClient: matrixClient,
-    roomId: '!roomId:matrix.org',
   });
 
   return (
-    <div>
+    <MantineProvider>
       <div>Connection: {connectionStatus}</div>
-      <IxoEditor editor={editor} />
-    </div>
+      <IxoEditor editor={editor} connectedUsers={connectedUsers} awarenessInstance={awarenessInstance} />
+    </MantineProvider>
   );
 }
 ```
 
-### Dark Theme
+The hook returns `{ editor, connectionStatus, title, yDoc, root, flowArray, connectedUsers, awarenessInstance }`. `permissions.write` defaults to `false` (read-only). See [`docs/architecture/architecture-overview.md`](docs/architecture/architecture-overview.md) for the Y.Doc structure and [`docs/authorization/matrix-permissions.md`](docs/authorization/matrix-permissions.md) for the access model.
 
-```tsx
-const editor = useCreateIxoEditor({
-  theme: 'dark',
-});
-```
+## Providing handlers
 
-### Read-Only Mode
+The editor is **domain-agnostic**: it never imports blockchain, DAO, or API code. The host app injects that behavior as `handlers` (and optional `blockRequirements`) on `<IxoEditor>`. Blocks and action types call into these to fetch data and perform side effects.
 
 ```tsx
-const editor = useCreateIxoEditor({
-  editable: false,
-  sideMenu: false,
-  slashMenu: false,
-  formattingToolbar: false,
-});
+<IxoEditor
+  editor={editor}
+  handlers={{
+    getCurrentUser: () => ({ address: wallet.address, name: wallet.name }),
+    submitClaim: async (params) => cosmos.submitClaim(params),
+    sendNotification: async (params) => api.notify(params),
+    // …implement the handlers your blocks/action types require
+  }}
+  blockRequirements={{ proposal: { coreAddress: dao.coreAddress } }}
+/>
 ```
 
-## Custom Blocks
+The full `BlocknoteHandlers` surface (proposals, claims, bids, lists, notifications, domain creation, UCAN signing, user search, …) is exported and documented in [`docs/architecture/architecture-overview.md`](docs/architecture/architecture-overview.md#handlers-external-integration-layer). For action types specifically, handlers are adapted into `ctx.services` via `buildServicesFromHandlers` — see the [action registry](#action-registry) section and [`docs/guides/action-block-pattern.md`](docs/guides/action-block-pattern.md).
 
-The IXO Editor includes custom blocks for working with IXO ecosystem data, available in both UI versions:
+## `useCreateIxoEditor` options
 
-### List Block
+| Option              | Type                              | Default            | Description                                  |
+| ------------------- | --------------------------------- | ------------------ | -------------------------------------------- |
+| `theme`             | `'light' \| 'dark'`               | `'light'`          | Editor color theme                           |
+| `docType`           | `'template' \| 'flow'`            | `'flow'`           | Design vs execution mode (local, not synced) |
+| `initialContent`    | `PartialBlock[]`                  | `undefined`        | Initial editor content                       |
+| `uploadFile`        | `(file: File) => Promise<string>` | Data-URL converter | File upload handler                          |
+| `editable`          | `boolean`                         | `true`             | Whether the editor is editable               |
+| `sideMenu`          | `boolean`                         | `true`             | Show side menu (drag handle, plus button)    |
+| `slashMenu`         | `boolean`                         | `true`             | Enable slash command menu                    |
+| `formattingToolbar` | `boolean`                         | `true`             | Show formatting toolbar                      |
+| `linkToolbar`       | `boolean`                         | `true`             | Show link toolbar                            |
+| `filePanel`         | `boolean`                         | `true`             | Show file panel                              |
+| `tableHandles`      | `boolean`                         | `true`             | Show table manipulation handles              |
 
-The List block displays dynamic data from DID and fragment identifiers, perfect for displaying data from your GraphQL API.
+`useCreateCollaborativeIxoEditor` extends these with `roomId`, `matrixClient`, `user`, `permissions`, and optional `docId` / `title` / `sourceTemplateId` (`IxoCollaborativeEditorOptions`).
 
-### Overview Block
+## `<IxoEditor>` props (selected)
 
-The Overview block provides a comprehensive view of entity data from DID identifiers.
+| Prop                                                | Type                         | Description                                   |
+| --------------------------------------------------- | ---------------------------- | --------------------------------------------- |
+| `editor`                                            | `IxoEditorType \| undefined` | Instance from a create hook                   |
+| `handlers`                                          | `BlocknoteHandlers`          | Host integration callbacks for blocks/actions |
+| `blockRequirements`                                 | `BlockRequirements`          | Runtime context data for specific blocks      |
+| `translate`                                         | `Translate`                  | i18n function (`t`) from the host app         |
+| `mantineTheme`                                      | `MantineTheme`               | Theme object to apply to the editor subtree   |
+| `onChange`                                          | `() => void`                 | Fired on content change                       |
+| `onSelectionChange`                                 | `() => void`                 | Fired on selection change                     |
+| `connectedUsers` / `awarenessInstance`              | see collaborative hook       | Enable per-block presence indicators          |
+| `className`, `children`, `coverImageUrl`, `logoUrl` | —                            | Layout/customization slots                    |
 
-#### Usage
+See `IxoEditorProps` in the exported types for the complete list.
 
-Both blocks can be inserted using the slash menu:
+## Core concepts
 
-**List Block:**
+### Flow engine
 
-1. Type `/list` in the editor
-2. Or type `/` and search for "List", "data", or "dynamic"
-3. Configure the DID and fragment identifier in the settings
+`@ixo/editor/core` (`src/core/lib/flowEngine/`) runs a block through a four-stage pipeline:
 
-**Overview Block:**
+1. **Activation** — are upstream dependency conditions satisfied?
+2. **Authorization** — is the current actor permitted (whitelist or UCAN delegation chain)?
+3. **Execution** — `executeNode(...)` orchestrates invocation → action → storage.
+4. **Runtime** — a Y.Map-backed `FlowRuntimeStateManager` tracks per-block state (`idle`/`running`/`completed`/`failed`) and syncs it via CRDT.
 
-1. Type `/overview` in the editor
-2. Or type `/` and search for "Overview", "overview-block", or "data-overview"
-3. Configure the DID in the settings
+Runtime state is the source of truth for a block's result — never mirror it into local React state. This rule is spelled out in [`CLAUDE.md`](CLAUDE.md) and [`docs/architecture/block-runtime-state.md`](docs/architecture/block-runtime-state.md).
 
-#### Programmatic Usage
+### Action registry
 
-```tsx
-// Insert a list block programmatically
-editor.insertBlocks(
-  [
-    {
-      type: 'list',
-      props: {
-        title: 'My Data List',
-        did: 'did:ixo:entity123',
-        fragmentIdentifier: 'claims-data',
-      },
-    },
-  ],
-  editor.getTextCursorPosition().block,
-  'after'
-);
-
-// Insert an overview block programmatically
-editor.insertBlocks(
-  [
-    {
-      type: 'overview',
-      props: {
-        did: 'did:ixo:entity123',
-      },
-    },
-  ],
-  editor.getTextCursorPosition().block,
-  'after'
-);
-```
-
-## UI Library Comparison
+The generic `action` block dispatches to a registered action type keyed by a `can` string (`qi/<namespace>.<verb>`). Each action type declares its inputs, output schema, and a `run()` that calls into `ctx.services`. The host app implements the underlying handlers; `buildServicesFromHandlers` wires them in. To add one, follow [`docs/guides/action-block-pattern.md`](docs/guides/action-block-pattern.md) and, for signed actions, [`docs/guides/slide-to-sign-and-diff-guide.md`](docs/guides/slide-to-sign-and-diff-guide.md).
 
-| Feature           | Shadcn UI            | Mantine UI            |
-| ----------------- | -------------------- | --------------------- |
-| **Bundle Size**   | ~46KB CSS            | ~173KB CSS            |
-| **Custom Blocks** | Full-featured        | Minimal (expandable)  |
-| **Theming**       | Tailwind-based       | CSS-in-JS             |
-| **Dependencies**  | Radix UI primitives  | Mantine ecosystem     |
-| **Customization** | High (CSS variables) | High (theme provider) |
+### UCAN authorization
 
-### When to Choose Shadcn UI
+Flow owners (`flowOwnerDid`) issue **delegations** granting specific actors permission to execute specific blocks; **invocations** record proof of execution. Both live in dedicated Y.Doc maps and sync with the document. See [`docs/authorization/ucan-technical.md`](docs/authorization/ucan-technical.md) and [`docs/authorization/ucan-flow-authorization.md`](docs/authorization/ucan-flow-authorization.md).
 
-- ✅ You're already using Tailwind CSS
-- ✅ You prefer smaller bundle sizes
-- ✅ You want the full-featured custom blocks
-- ✅ You like CSS variable-based theming
+### Flow compiler & flow agent
 
-### When to Choose Mantine UI
+The **flow compiler** (`src/core/lib/flowCompiler/`) converts between a portable "Base UCAN" flow description and the live Y.Doc (`setupFlowFromBaseUcan`, `readFlowAsBaseUcan`, `compileBaseUcanFlow`, …), enabling flows to be authored, cloned, and merged. The **flow agent** runtime (`src/core/lib/flowAgent/`) drives automated progression of a flow (leases, command queue, policy evaluation, ledger) — see [`docs/flow-engine/`](docs/flow-engine/).
 
-- ✅ You're already using Mantine in your app
-- ✅ You prefer component-based theming
-- ✅ You want consistent Mantine design language
-- ✅ You plan to enhance the minimal blocks with Mantine components
+## Custom blocks
 
-## Development
+The IXO block schema is registered automatically by the create hooks. Blocks can be inserted from the slash menu (`/`) or programmatically:
 
-### Project Structure
-
-```
-ixo-editor/
-├── src/
-│   ├── core/            # Shared infrastructure
-│   │   ├── types.ts     # Shared types
-│   │   ├── hooks/       # Matrix provider
-│   │   └── lib/         # GraphQL client & utilities
-│   ├── shadcn/          # Shadcn UI implementation
-│   │   ├── IxoEditor.tsx
-│   │   ├── blocks/      # Full-featured custom blocks
-│   │   ├── components/  # Shadcn UI components
-│   │   ├── hooks/       # Editor hooks
-│   │   └── index.ts     # Shadcn exports
-│   ├── mantine/         # Mantine UI implementation
-│   │   ├── IxoEditor.tsx
-│   │   ├── blocks/      # Minimal custom blocks
-│   │   ├── hooks/       # Editor hooks
-│   │   └── index.ts     # Mantine exports
-│   ├── styles/          # Source CSS
-│   │   └── ixo-editor.css
-│   └── index.ts         # Main entry (defaults to shadcn)
-├── fonts/               # Inter font files
-├── dist/                # Built JavaScript
-│   ├── index.js         # Main bundle
-│   ├── shadcn/          # Shadcn bundle
-│   └── mantine/         # Mantine bundle
-├── style*.css           # CSS bundles
-└── package.json
+```tsx
+editor.insertBlocks([{ type: 'list', props: { title: 'Members', did: 'did:ixo:entity123', fragmentIdentifier: 'members' } }], editor.getTextCursorPosition().block, 'after');
 ```
 
-### Building the Package
+The full block catalog, prop schemas, and conditional-logic system are documented in [`docs/architecture/architecture-overview.md`](docs/architecture/architecture-overview.md) and [`docs/architecture/editor-type-map.md`](docs/architecture/editor-type-map.md).
 
-```bash
-# Install dependencies
-pnpm install
-
-# Build the package (creates all bundles)
-pnpm build
+## Server-side usage
 
-# Watch for changes during development
-pnpm run dev
+Consumers that only need flow logic (e.g. an oracle validating or advancing a flow) can import the UI-free core:
 
-# Type checking
-pnpm run type-check
+```ts
+import { executeNode, isAuthorized, createUcanService, compileBaseUcanFlow, tickFlowAgent } from '@ixo/editor/core';
 ```
 
-## Requirements
-
-- React 18.0.0 or higher
-- React DOM 18.0.0 or higher
-- Modern browser with ES2020 support
-- For collaborative editing: Matrix server access
-
-### Additional Requirements by UI Library
-
-**For Mantine version:**
+This entry point pulls in **no** React, Mantine, or BlockNote code.
 
-- `@mantine/core` ^8.0.0 (peer dependency)
-- `@mantine/hooks` ^8.0.0 (peer dependency)
+## Documentation
 
-**For Shadcn version:**
+All documentation lives in [`docs/`](docs/) and is indexed by [`docs/README.md`](docs/README.md). Highlights:
 
-- Works with existing Tailwind CSS setup
-- No additional peer dependencies
+- [`docs/architecture/architecture-overview.md`](docs/architecture/architecture-overview.md) — the definitive system reference.
+- [`docs/authorization/flows-actions-ucans-explained.md`](docs/authorization/flows-actions-ucans-explained.md) — flows, actions & UCANs from zero.
+- [`docs/guides/`](docs/guides/) — building action blocks, slide-to-sign + diff views, styling.
+- [`docs/authorization/`](docs/authorization/) — UCANs, signing, Matrix permissions.
+- [`docs/flow-engine/`](docs/flow-engine/) — engine design rationale and roadmap.
+- [`docs/integrations/`](docs/integrations/) — third-party integrations (Calendar, Xero via Composio).
+- [`CLAUDE.md`](CLAUDE.md) — project rules and the condensed runtime-state canon.
+- [`CONTEXT.md`](CONTEXT.md) — domain glossary (ubiquitous language).
 
-## Migration Guide
-
-### From v1.x to v2.x (Multi-UI)
-
-**Before (v1.x):**
+## Development
 
-```tsx
-import { IxoEditor } from '@ixo/editor';
-import '@blocknote/shadcn/style.css';
-import '@ixo/editor/style.css';
+```bash
+pnpm install          # install dependencies
+pnpm build            # build all bundles (tsup → dist/, + CSS)
+pnpm run dev          # rebuild on change
+pnpm run type-check   # tsc --noEmit
+pnpm test             # vitest
+pnpm run example:action-gallery   # run the action-type gallery example app
 ```
 
-**After (v2.x) - Recommended:**
+### Project structure
 
-```tsx
-// Explicit shadcn version with complete CSS bundle
-import { IxoEditor } from '@ixo/editor/shadcn';
-import '@ixo/editor/style-shadcn.css'; // Single import!
+```
+editor/
+├── src/
+│   ├── core/            # UI-free core (flow engine, action registry, UCAN,
+│   │   │                #   flow compiler, flow agent, types, GraphQL client)
+│   │   └── index.ts     # @ixo/editor/core entry
+│   ├── mantine/         # Mantine editor: IxoEditor, hooks, blocks, components, context
+│   │   └── index.ts     # @ixo/editor/mantine entry
+│   ├── styles/          # Source CSS
+│   ├── data/ icons/ images/   # Static assets
+│   ├── test-utils/      # Test helpers
+│   └── index.ts         # Default entry (Mantine + full public API)
+├── docs/                # Documentation (see docs/README.md)
+├── examples/            # Example apps & configs (action-type-gallery, …)
+├── plans/               # Implementation plans
+├── fonts/               # Inter font files
+├── dist/                # Build output (generated)
+├── style*.css           # Published CSS bundles (generated)
+└── package.json
 ```
 
-**After (v2.x) - Backward compatible:**
+## Requirements
 
-```tsx
-// Still works! (defaults to shadcn)
-import { IxoEditor } from '@ixo/editor';
-import '@ixo/editor/style.css'; // Now includes all dependencies
-```
+- React 18+ and React DOM 18+
+- Mantine 7 (`@mantine/core`, `@mantine/hooks`, `@mantine/dates`)
+- A modern browser (ES2020+)
+- For collaboration: a Matrix server, `matrix-js-sdk`, and `@ixo/matrix-crdt`
 
-## License
+## Migration
 
-MIT © IXO Team
+### v2 (multi-UI) → v6 (Mantine-only)
 
----
+The Shadcn UI variant and its `@ixo/editor/shadcn` / `style-shadcn.css` entry points have been **removed**. Use the default or `/mantine` entry:
 
-## Internal Notes
+```tsx
+// Before (v2)
+import { IxoEditor } from '@ixo/editor/shadcn';
+import '@ixo/editor/style-shadcn.css';
 
-This package is maintained by the IXO development team. For questions or issues, please contact the team directly through internal channels.
+// Now (v6)
+import { IxoEditor, useCreateIxoEditor } from '@ixo/editor';
+import '@ixo/editor/style.css';
+```
 
-### Version Management
+The editor also evolved from a rich-text wrapper into a full workflow/flow engine — the flow engine, action registry, UCAN authorization, flow compiler, and flow agent are new since v2. See the [documentation](#documentation) to adopt them.
 
-Follow semantic versioning:
+## Contributing
 
-- Patch releases (0.0.x): Bug fixes and minor updates
-- Minor releases (0.x.0): New features that are backward compatible
-- Major releases (x.0.0): Breaking changes (like the multi-UI restructure)
+Internal package. Use [Conventional Commits](https://www.conventionalcommits.org/) (enforced by commitlint; releases are automated via semantic-release). See [`CLAUDE.md`](CLAUDE.md) for project rules and commit format. Record structural repo/doc reorganizations in [`ORGANIZATION-LOG.md`](ORGANIZATION-LOG.md).
 
-### Contributing
+## License
 
-This is an internal package. All contributions should go through the standard IXO development workflow and review process.
+MIT © IXO Team