@ai-matrx/chat 0.1.74 → 0.2.0

package/dist/surfaces/manifests/_conversation-document.manifest.js

@@ -0,0 +1,317 @@
+const CONVERSATION_DOCUMENT_GROUPS = [
+  {
+    key: "active_scope",
+    label: "Working selection",
+    sortOrder: 100,
+    description: "What the user is acting on right now \u2014 the selection or the whole body, plus the surrounding heading and cursor."
+  },
+  {
+    key: "document_identity",
+    label: "Document identity",
+    sortOrder: 200,
+    description: "Which document this is and where it durably persists."
+  },
+  {
+    key: "document_state",
+    label: "Document state",
+    sortOrder: 300,
+    description: "Live editor state: unsaved/saving/conflict standing, the concurrency version, and size signals."
+  },
+  {
+    key: "conversation_link",
+    label: "Conversation link",
+    sortOrder: 400,
+    description: "The conversation this document hangs off \u2014 a reference plus what the link makes available. Never the conversation's own content."
+  }
+];
+const CONVERSATION_DOCUMENT_VALUES = [
+  // ── Selection / scope mirror (210-259) ─────────────────────────────────
+  {
+    name: "active_text",
+    label: "Active text",
+    description: "What the user is acting on: the highlighted selection if any text is selected, otherwise the full document body. Empty when the document is empty. Wire here for an agent that should follow the user's intent \u2014 'run on selection if there is one, run on the whole document otherwise'.",
+    valueType: "string",
+    alwaysAvailable: false,
+    typicalCharCount: 4e3,
+    sortOrder: 210,
+    group: "active_scope"
+  },
+  {
+    name: "active_scope_kind",
+    label: "Active scope kind",
+    description: '"selection" when text is highlighted, "document" when no selection but the document has content, "empty" when the document is empty. Lets an agent reason about what `active_text` represents on this run.',
+    valueType: "string",
+    alwaysAvailable: true,
+    typicalCharCount: 10,
+    sortOrder: 220,
+    group: "active_scope"
+  },
+  {
+    name: "current_heading",
+    label: "Current heading",
+    description: "Nearest markdown heading above the cursor, with leading hashes stripped. Empty when no heading precedes the cursor. Lets section-aware actions target the surrounding heading without parsing the markdown themselves.",
+    valueType: "string",
+    alwaysAvailable: false,
+    typicalCharCount: 60,
+    sortOrder: 230,
+    group: "active_scope"
+  },
+  {
+    name: "current_section_text",
+    label: "Current section text",
+    description: "Text under `current_heading`, from the heading line through to (but not including) the next heading of equal or higher level \u2014 or end of document. Empty when no heading precedes the cursor. Wire here for 'rewrite this section' actions that operate on a heading-bounded block.",
+    valueType: "string",
+    alwaysAvailable: false,
+    typicalCharCount: 1500,
+    sortOrder: 240,
+    group: "active_scope"
+  },
+  {
+    name: "cursor_offset",
+    label: "Cursor character offset",
+    description: "0-indexed character offset of the cursor into the document body. When a selection exists this is `selectionStart`. Useful for 'insert at cursor' actions. Zero when the document is empty.",
+    valueType: "number",
+    alwaysAvailable: false,
+    typicalCharCount: 6,
+    sortOrder: 250,
+    group: "active_scope"
+  },
+  // ── Document identity & metadata (300-359) ─────────────────────────────
+  {
+    name: "document_id",
+    label: "Document ID",
+    description: "UUID of the durable `cx_working_documents` row backing this document. Empty while the document is ephemeral (Redux-only) or bound to a note instead. Required for any action that writes the durable row directly.",
+    valueType: "string",
+    alwaysAvailable: false,
+    typicalCharCount: 36,
+    sortOrder: 300,
+    group: "document_identity"
+  },
+  {
+    name: "document_title",
+    label: "Document title",
+    description: "User-given title of the document. Empty when the user hasn't named it yet.",
+    valueType: "string",
+    alwaysAvailable: false,
+    typicalCharCount: 60,
+    sortOrder: 310,
+    group: "document_identity"
+  },
+  {
+    name: "document_kind",
+    label: "Document kind",
+    description: `"working" for the shared collaborative document (the cloud agent reads and writes it) or "scratch" for the user's private scratchpad (the cloud agent only reads it). Always present \u2014 it is fixed per surface.`,
+    valueType: "string",
+    alwaysAvailable: true,
+    typicalCharCount: 8,
+    sortOrder: 320,
+    group: "document_identity"
+  },
+  {
+    name: "binding_kind",
+    label: "Document binding",
+    description: 'Where the document persists: "cx_working_document" (the durable per-conversation row, the default), "note" (synced to a `workbench.notes` row), "studio_document" (Scribe\'s source), or "none" (ephemeral). Lets an action know whether/where edits durably land.',
+    valueType: "string",
+    alwaysAvailable: false,
+    typicalCharCount: 20,
+    sortOrder: 330,
+    group: "document_identity"
+  },
+  {
+    name: "binding_id",
+    label: "Bound source ID",
+    description: "UUID of the durable row this document persists into, whatever the binding kind is (working-document row, note, or studio document). Empty when the document is ephemeral (`binding_kind` = none). Broader than `document_id`, which is only the working-document row.",
+    valueType: "string",
+    alwaysAvailable: false,
+    typicalCharCount: 36,
+    sortOrder: 332,
+    group: "document_identity",
+    autoContext: false
+  },
+  {
+    name: "binding_label",
+    label: "Bound source label",
+    description: "Display label of the bound source, latched when the binding was made (e.g. the note's title). Empty when unbound or never labeled.",
+    valueType: "string",
+    alwaysAvailable: false,
+    typicalCharCount: 60,
+    sortOrder: 334,
+    group: "document_identity",
+    autoContext: false
+  },
+  {
+    name: "is_dirty",
+    label: "Has unsaved changes",
+    description: "True when the editor has local edits not yet persisted to the durable source. False when clean. Lets an agent prompt to save first or refuse to act on stale state.",
+    valueType: "boolean",
+    alwaysAvailable: false,
+    typicalCharCount: 5,
+    sortOrder: 340,
+    group: "document_state"
+  },
+  {
+    name: "word_count",
+    label: "Word count",
+    description: "Whitespace-delimited word count of the document body. Zero when empty. Lets actions adapt to content size (summarize-vs-skip thresholds).",
+    valueType: "number",
+    alwaysAvailable: false,
+    typicalCharCount: 6,
+    sortOrder: 350,
+    group: "document_state"
+  },
+  {
+    name: "char_count",
+    label: "Character count",
+    description: "Character length of the document body. Zero when empty. The cheap size signal an action can check before pulling the whole body.",
+    valueType: "number",
+    alwaysAvailable: false,
+    typicalCharCount: 6,
+    sortOrder: 352,
+    group: "document_state",
+    autoContext: false
+  },
+  {
+    name: "is_saving",
+    label: "Save in flight",
+    description: "True while a persist to the bound durable source is in flight. False when idle. Always emitted \u2014 the editor always knows its persist state.",
+    valueType: "boolean",
+    alwaysAvailable: true,
+    typicalCharCount: 5,
+    sortOrder: 354,
+    group: "document_state",
+    autoContext: false
+  },
+  {
+    name: "is_materialized",
+    label: "Durable row exists",
+    description: "True once the durable row actually exists. False while the document is enabled with a reserved id but no row yet (materialize-on-write). Always emitted. An action that writes the row directly must tolerate false.",
+    valueType: "boolean",
+    alwaysAvailable: true,
+    typicalCharCount: 5,
+    sortOrder: 356,
+    group: "document_state",
+    autoContext: false
+  },
+  {
+    name: "document_version",
+    label: "Document version",
+    description: "The durable row `version` the local content is based on \u2014 the optimistic-concurrency token. Zero while the document has no durable row. Always emitted.",
+    valueType: "number",
+    alwaysAvailable: true,
+    typicalCharCount: 3,
+    sortOrder: 358,
+    group: "document_state",
+    autoContext: false
+  },
+  {
+    name: "has_conflict",
+    label: "Unresolved edit conflict",
+    description: "True when the user's save was refused because a concurrent edit (usually the agent this turn) advanced the row, and the conflict is still unresolved. Auto-save is blocked while true \u2014 an agent should not write the document until the user reconciles. Always emitted.",
+    valueType: "boolean",
+    alwaysAvailable: true,
+    typicalCharCount: 5,
+    sortOrder: 359,
+    group: "document_state"
+  },
+  {
+    name: "editor_mode",
+    label: "Editor mode",
+    description: 'Which editing surface the user has open \u2014 "plain" (raw markdown textarea) or the rich/preview mode. Always emitted; tells an action whether the user is looking at source or rendered output.',
+    valueType: "string",
+    alwaysAvailable: true,
+    typicalCharCount: 10,
+    sortOrder: 357,
+    group: "document_state",
+    autoContext: false
+  },
+  // ── Conversation relationship (360-389) ────────────────────────────────
+  // The document HANGS OFF a conversation but the conversation is not its
+  // context — it's a reference plus the dict made available through the link.
+  {
+    name: "conversation_id",
+    label: "Conversation ID",
+    description: "UUID of the conversation this document is attached to. Always present (a document is always conversation-scoped). A reference/link \u2014 not the conversation's content. Use to relate the document back to its chat.",
+    valueType: "string",
+    alwaysAvailable: true,
+    typicalCharCount: 36,
+    sortOrder: 360,
+    group: "conversation_link"
+  },
+  {
+    name: "conversation_context",
+    label: "Conversation context",
+    description: "The host conversation's assembled context dict (its instanceContext entries \u2014 scope values, working-doc value, ambient context) made available to agents acting inside the document. Empty object when the host supplied none. Bind here when a document-surface agent should also see what the chat agent sees.",
+    valueType: "object",
+    alwaysAvailable: false,
+    typicalCharCount: 1500,
+    sortOrder: 370,
+    group: "conversation_link"
+  },
+  {
+    name: "active_scope_ids",
+    label: "Active scope IDs",
+    description: "Array of scope UUIDs the user has selected as active context in the host conversation (org / department / case / patient, etc.). Empty array when none. Lets a document-surface agent resolve the same scope cells the chat agent uses.",
+    valueType: "array",
+    alwaysAvailable: false,
+    typicalCharCount: 360,
+    sortOrder: 380,
+    group: "conversation_link"
+  }
+];
+const CONVERSATION_DOCUMENT_WRITE_TARGETS = [
+  {
+    name: "document_content",
+    label: "Document content",
+    description: "REPLACES the ENTIRE document body with the plain text you pass. This is a full replacement, not a merge: read `content` first and include every line that should survive, or use `append_document_content` / `replace_selection` when you only mean to change part of it. Pass the markdown itself \u2014 no ``` code fence and no commentary. Must be non-empty; clearing the document is a human gesture, so an empty string is refused. It lands exactly as if the user had typed it \u2014 on screen at once, then autosaved to the document about a second later. There is no Save step. Refused while an unresolved edit conflict is pending.",
+    valueType: "string",
+    updatesValue: "content",
+    approvalComparison: "text-replacement",
+    mode: "entity",
+    applyPolicy: "ask",
+    group: "active_scope",
+    sortOrder: 100
+  },
+  {
+    name: "append_document_content",
+    label: "Added content",
+    description: "APPENDS the plain text you pass to the END of the document, separated by a blank line. Nothing already in the document is touched or re-sent \u2014 pass ONLY the new text, never the whole body. Use this to add a section, an example, or a closing paragraph; use `document_content` when the whole document is being rewritten. No ``` code fence, no commentary. Must be non-empty. It lands exactly as if the user had typed it \u2014 on screen at once, then autosaved about a second later, with no Save step. Refused while an unresolved edit conflict is pending.",
+    valueType: "string",
+    updatesValue: "content",
+    mode: "entity",
+    applyPolicy: "ask",
+    group: "active_scope",
+    sortOrder: 110
+  },
+  {
+    name: "replace_selection",
+    label: "Selected text",
+    description: 'REPLACES exactly the user\'s highlighted range with the plain text you pass \u2014 nothing outside the selection is touched. This is the precise target: prefer it whenever `active_scope_kind` is "selection", so a rewrite of one paragraph does not resend the whole document. Pass the replacement text only, with no ``` code fence and no commentary. REFUSED when nothing is selected \u2014 a select-aware request needs a real selection, and guessing a range would silently overwrite the wrong text; ask the user to highlight the passage instead. Autosaved about a second after it lands; no Save step. Refused while an unresolved edit conflict is pending.',
+    valueType: "string",
+    updatesValue: "selection",
+    approvalComparison: "text-replacement",
+    mode: "entity",
+    applyPolicy: "ask",
+    group: "active_scope",
+    sortOrder: 120
+  },
+  {
+    name: "insert_at_cursor",
+    label: "Inserted text",
+    description: "INSERTS the plain text you pass at the user's caret (`cursor_offset`), or immediately AFTER the highlighted range when there is a selection \u2014 nothing existing is removed or re-sent. Use this to add a paragraph, a list, or a table at the point the user is working, rather than rewriting what is already there. A blank line is placed around the insertion, so pass the text alone without leading or trailing newlines. No ``` code fence, no commentary. Must be non-empty. Autosaved about a second after it lands; no Save step. Refused while an unresolved edit conflict is pending.",
+    valueType: "string",
+    updatesValue: "content",
+    mode: "entity",
+    applyPolicy: "ask",
+    group: "active_scope",
+    sortOrder: 130
+  }
+];
+function createConversationDocumentScope(values) {
+  return values;
+}
+export {
+  CONVERSATION_DOCUMENT_GROUPS,
+  CONVERSATION_DOCUMENT_VALUES,
+  CONVERSATION_DOCUMENT_WRITE_TARGETS,
+  createConversationDocumentScope
+};

package/dist/surfaces/manifests/admin-ui-surfaces.manifest.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Surface manifest — UI Surfaces registry (`matrx-admin/ui-surfaces`).
+ *
+ * ADMIN SURFACE. The LIST route `/administration/ui/surfaces` exactly
+ * (`app/(admin)/administration/ui/surfaces/page.tsx` →
+ * `features/surfaces/components/SurfacesContainer.tsx`): every row of
+ * `ui.ui_surface` (the platform's own records — no org or person lanes), with
+ * its readiness, its check-ledger age, its synced value / agent / tool counts,
+ * and the Drift report / Sync manifests / New client / Candidates actions.
+ * The per-surface editor at `/administration/ui/surfaces/<name>` is a
+ * different page (one record) and has no surface yet — the route mapping is
+ * an exact regex so it never borrows this list's vocabulary.
+ *
+ * Emitter: `SurfacesContainer.tsx` mounts `<SurfaceRuntimeProvider>` around
+ * the canonical right-click menu; the scope is built by the pure
+ * `buildUiSurfacesScope` (`features/surfaces/lib/ui-surfaces-scope.ts`) from
+ * the rows the page already loaded (never fetches).
+ *
+ * Write half — ONE record type (surfaces), full list CRUD plus
+ * `new_surface_draft` (fills the New surface dialog; nothing saved), all `ask`, through
+ * the page's own service functions (`createSurface` / `updateSurface` /
+ * `deleteSurface`); pure parsers in `features/surfaces/lib/ui-surfaces-agent-writes.ts`.
+ *  - A surface WITH a code manifest is owned by code: the next Sync manifests
+ *    rewrites its label, description, parent, url pattern and active flag, so
+ *    `update_surfaces` refuses those fields on it (only sort_order and
+ *    executor_name stick), and `delete_surfaces` refuses it outright (code owns
+ *    it; remove the manifest in code instead).
+ *  - Delete means archive (Arman, 2026-09-27): `delete_surfaces` moves the row
+ *    to Trash (deleted_at). Config, item types and tool defaults follow via the
+ *    platform soft-delete cascade; everything comes back on restore from Trash.
+ *
+ * NOT writable: UI clients (not listed on this page — they appear only as
+ * filter options; the New client dialog stays a human action), readiness and
+ * the check ledger (evidence written by the certification loop), and every
+ * count (derived).
+ */
+import type { SurfaceManifest, SurfaceScopePayload } from "../types.js";
+export declare const ADMIN_UI_SURFACES_SURFACE_NAME = "matrx-admin/ui-surfaces";
+export declare const adminUiSurfacesManifest: SurfaceManifest;
+/** One entry of `surfaces`. */
+export interface UiSurfaceScopeEntry {
+    name: string;
+    label: string | null;
+    client_name: string;
+    executor_name: string | null;
+    parent_surface_name: string | null;
+    sort_order: number;
+    tier: string;
+    is_active: boolean;
+    readiness: string;
+    readiness_note: string | null;
+    has_manifest: boolean;
+    value_count: number;
+    /** Values the code manifest declares (with inherited ones); null = no manifest. */
+    declared_value_count: number | null;
+    agent_count: number;
+    tool_count: number;
+    check_state: string;
+    last_checked_at: string | null;
+    last_checked_by: string | null;
+    url_pattern: string | null;
+    description: string | null;
+}
+export interface UiSurfacesRegistryCounts {
+    total: number;
+    active: number;
+    manifests: number;
+    unused: number;
+    visible: number;
+    readiness: Record<"verified" | "partial" | "stub" | "unregistered", number>;
+    candidates_available: number;
+    drift_issues?: number;
+}
+export interface UiSurfacesFilterScope {
+    client: string;
+    status: string;
+    check_age: string;
+    manifest: string;
+    parent: string;
+    readiness: string;
+}
+/**
+ * Type-safe payload helper. Required keys mirror `alwaysAvailable: true`;
+ * optional keys mirror `alwaysAvailable: false`.
+ */
+export declare function createAdminUiSurfacesScope(values: {
+    load_state: string;
+    filters: UiSurfacesFilterScope;
+    selection?: string;
+    context?: Record<string, unknown>;
+    surface_list?: string;
+    surfaces?: UiSurfaceScopeEntry[];
+    registry_counts?: UiSurfacesRegistryCounts;
+    client_names?: string[];
+    peeked_surface?: string;
+    open_dialog?: string;
+    new_surface_draft?: {
+        name: string;
+        client: string;
+        local: string;
+        parent_surface_name: string | null;
+        tier: string;
+        description: string;
+    };
+}): SurfaceScopePayload;

package/dist/surfaces/manifests/admin-ui-surfaces.manifest.js

@@ -0,0 +1,197 @@
+import { mergeBaselineValues, pickBaseline } from "./_baseline.manifest.js";
+import { MATRX_WEB_APP_EXECUTOR } from "../executor.js";
+const ADMIN_UI_SURFACES_SURFACE_NAME = "matrx-admin/ui-surfaces";
+const groups = [
+  {
+    key: "registry",
+    label: "Surface registry",
+    sortOrder: 100,
+    description: "Every UI surface in the registry, the rows the list shows, and the headline counts."
+  },
+  {
+    key: "view",
+    label: "View",
+    sortOrder: 200,
+    description: "The page's filters, the peeked surface and the open dialog."
+  }
+];
+const SURFACE_SHAPE = "{ name, label, client_name, executor_name, parent_surface_name, sort_order, tier, is_active, readiness, readiness_note, has_manifest, value_count (values saved in the database), declared_value_count (values its code manifest declares; null with no manifest \u2014 when the two differ, Sync manifests brings the database up to date), agent_count, tool_count, check_state, last_checked_at, last_checked_by, url_pattern, description }";
+const surfaceSpecific = [
+  {
+    name: "load_state",
+    label: "Load state",
+    description: '"loading" while the registry loads, "ready" after a successful load, or "error: <message>" when it failed (then no counts or rows are reported). Always present.',
+    valueType: "string",
+    alwaysAvailable: true,
+    typicalCharCount: 8,
+    sortOrder: 100,
+    group: "registry"
+  },
+  {
+    name: "surface_list",
+    label: "Surfaces on screen",
+    description: "The rows the list shows after the page's own filters (client, status, check age, manifests, parent, readiness tile), condensed as one XML bundle: <surfaces total shown filters\u2026><s name label client parent tier readiness values declared agents tools checked active manifest/> (values = saved in the database, declared = in its code manifest)\u2026</surfaces>, first 40 in the page's default order (tier, then name). The table's own search box and column sort are not reflected (the table does not report them). Absent until the registry has loaded.",
+    valueType: "string",
+    alwaysAvailable: false,
+    typicalCharCount: 3500,
+    inlineUpTo: 4e3,
+    sortOrder: 105,
+    group: "registry"
+  },
+  {
+    name: "surfaces",
+    label: "All surfaces",
+    description: `Every surface in the registry (every row, not only the filtered ones), each ${SURFACE_SHAPE}. has_manifest is true when a code manifest owns the surface; check_state is "never" | "stale" | "fresh". Use the names with update_surfaces / delete_surfaces. Absent until the registry has loaded.`,
+    valueType: "array",
+    alwaysAvailable: false,
+    typicalCharCount: 6e4,
+    sortOrder: 110,
+    group: "registry"
+  },
+  {
+    name: "registry_counts",
+    label: "Registry counts",
+    description: "{ total, active, manifests, unused, visible, readiness: { verified, partial, stub, unregistered }, candidates_available, drift_issues? } \u2014 the numbers in the page's toolbar and readiness tiles. readiness counts follow the client filter, as the tiles do; unused = surfaces with no agents and no tools (the toolbar says 'with no agents or tools'); drift_issues = the Drift report's total issue count (what its button badge shows), omitted until that report loads. Absent until the registry has loaded.",
+    valueType: "object",
+    alwaysAvailable: false,
+    typicalCharCount: 200,
+    inlineUpTo: 400,
+    sortOrder: 120,
+    group: "registry"
+  },
+  {
+    name: "client_names",
+    label: "UI clients",
+    description: "The UI client names a surface can belong to (e.g. matrx-user, matrx-admin). A surface name is always <client>/<local>. Absent until loaded.",
+    valueType: "array",
+    alwaysAvailable: false,
+    typicalCharCount: 150,
+    inlineUpTo: 300,
+    sortOrder: 130,
+    group: "registry"
+  },
+  {
+    name: "filters",
+    label: "Filters",
+    description: `{ client, status, check_age, manifest, parent, readiness } \u2014 the page's filters, each "all" when unset. client is a client name; status "active" | "inactive"; check_age "never" | "stale" | "fresh"; manifest "with_manifest" | "without_manifest"; parent a surface name or "none" (root surfaces); readiness "verified" | "partial" | "stub" | "unregistered". Always present.`,
+    valueType: "object",
+    alwaysAvailable: true,
+    typicalCharCount: 120,
+    inlineUpTo: 300,
+    sortOrder: 200,
+    group: "view"
+  },
+  {
+    name: "peeked_surface",
+    label: "Peeked surface",
+    description: "The name of the surface open in the side peek panel. Absent when no peek panel is open.",
+    valueType: "string",
+    alwaysAvailable: false,
+    typicalCharCount: 30,
+    sortOrder: 210,
+    group: "view"
+  },
+  {
+    name: "open_dialog",
+    label: "Open dialog",
+    description: '"new_surface" | "new_client" | "candidates" | "sync_manifests" | "drift_report" when that dialog is open. Absent when none is open.',
+    valueType: "string",
+    alwaysAvailable: false,
+    typicalCharCount: 12,
+    sortOrder: 220,
+    group: "view"
+  },
+  {
+    name: "new_surface_draft",
+    label: "New surface draft",
+    description: `The New surface dialog's live values as { name, client, local, parent_surface_name, tier, description } \u2014 name is "<client>/<local>" ("" until both are set); parent_surface_name null means a root surface; tier is the dialog's tier label. The read twin of the new_surface_draft write target. Absent while the dialog is closed.`,
+    valueType: "object",
+    alwaysAvailable: false,
+    typicalCharCount: 200,
+    inlineUpTo: 800,
+    sortOrder: 230,
+    group: "view"
+  }
+];
+const SURFACE_FIELDS = 'name: string (required on create; "<client>/<local>", client one of client_names, local lowercase letters, digits, hyphens and slashes, e.g. "matrx-user/notes"), label?: string, description?: string, parent_surface_name?: string | null (an existing surface name; default "matrx-default/default"; null = root), sort_order?: number (a whole number \u2265 100: 100-299 Pages, 300-999 Specialized, 1000-1999 Overlays, 2000-8999 Editor variants, 9000+ Debug; default 150), is_active?: boolean (default true), executor_name?: string | null, url_pattern?: string | null';
+const writeTargets = [
+  {
+    name: "new_surface_draft",
+    label: "New surface form",
+    description: 'Opens the New surface dialog (if closed) and fills it in. NOTHING is saved \u2014 the person reviews it and presses Create. Value is a JSON OBJECT (not a string, not an array) with any of: { name: "<client>/<local>" (client one of client_names; local lowercase letters, digits, hyphens, slashes; must not exist yet), parent_surface_name: an existing surface name or null for a root surface, tier: "Pages" | "Specialized" | "Overlays" | "Editor variants" | "Debug", description: string }. Only the fields you send change. Every problem is reported at once and the dialog is left untouched. Use this for one surface the person wants to look over first; to create surfaces directly use create_surfaces.',
+    valueType: "object",
+    updatesValue: "new_surface_draft",
+    mode: "draft",
+    applyPolicy: "ask",
+    group: "view",
+    sortOrder: 100
+  },
+  {
+    name: "create_surfaces",
+    label: "Create surfaces",
+    description: `Creates one or more UI surface rows in the registry, saved immediately, exactly as the New surface dialog does. Value is a JSON ARRAY (not a string) of 1-25 objects, each { ${SURFACE_FIELDS} }, e.g. [{ "name": "matrx-user/reports", "label": "Reports", "description": "\u2026" }]. The whole list is checked first: a bad name, an unknown client or parent, a sort_order under 100, a name repeated in the list or already in the registry refuses everything, with every problem listed, and nothing is created. A registry row alone does not make a page agent-readable \u2014 that needs a code manifest; say so to the person.`,
+    valueType: "array",
+    updatesValue: "surfaces",
+    mode: "entity",
+    applyPolicy: "ask",
+    group: "registry",
+    sortOrder: 110
+  },
+  {
+    name: "update_surfaces",
+    label: "Update surfaces",
+    description: "Changes one or more surfaces, saved immediately. Value is a JSON ARRAY (not a string) of 1-25 objects, each { name: string (required, from surfaces), description?, parent_surface_name?, sort_order?, is_active?, executor_name?, url_pattern? } \u2014 fields read as in create_surfaces; only the fields you send change. is_active: false deactivates a surface (reversible; its bindings are kept). A surface with has_manifest true is owned by its code manifest: Sync manifests rewrites its description, parent, url pattern and active flag, so those fields are REFUSED on it \u2014 only sort_order and executor_name may change; to change the rest, change the manifest in code. Unknown names, a name twice, an unknown parent or a surface made its own parent refuse the whole list with nothing changed. The label is not editable here.",
+    valueType: "array",
+    updatesValue: "surfaces",
+    mode: "entity",
+    applyPolicy: "ask",
+    group: "registry",
+    sortOrder: 120
+  },
+  {
+    name: "delete_surfaces",
+    label: "Move surfaces to Trash",
+    description: 'Moves one or more surfaces to Trash (archives them; restorable from Trash with everything intact). Value is a JSON ARRAY (not a string) of surface names, or { name } objects, from surfaces. The surface disappears from the registry and agents stop seeing it; its config, item types and tool defaults move to Trash with it. To only hide a surface, prefer update_surfaces with { "name": "\u2026", "is_active": false }. A surface with has_manifest true is REFUSED (its code manifest owns it \u2014 remove the manifest in code). Unknown or repeated names refuse the whole list, with nothing moved.',
+    valueType: "array",
+    updatesValue: "surfaces",
+    mode: "entity",
+    applyPolicy: "ask",
+    group: "registry",
+    sortOrder: 130
+  }
+];
+const adminUiSurfacesManifest = {
+  surfaceName: ADMIN_UI_SURFACES_SURFACE_NAME,
+  client: "matrx-admin",
+  executor: MATRX_WEB_APP_EXECUTOR,
+  executionMode: "python-stream",
+  description: "UI Surfaces registry admin: every ui_surface row with readiness, check ledger, value/agent/tool counts and filters; create, update, deactivate and move surfaces to Trash (/administration/ui/surfaces).",
+  readiness: "partial",
+  readinessNote: "Emitter and write targets built 2026-09-27 (page-pass). Not yet proven: live surface:probe on the deployed commit, the live agent write test (create two / update one / deactivate one / one refusal) with a DB completeness check, and an outside-helper binding test. surface_list reflects the page's own filters, not the table's search box or column sort (MatrxDataTable does not report its visible rows).",
+  label: "UI Surfaces",
+  urlPattern: "/administration/ui/surfaces",
+  intro: `<surface_intro>
+You are on the UI Surfaces registry at /administration/ui/surfaces \u2014 an admin page listing every agent surface (a page or window agents can read) with its readiness, when its full check last completed, and how many values, agents and tools it has. surface_list is what the list shows (condensed, first 40); surfaces has every row in full; registry_counts has the headline numbers.
+
+Changes go through these targets, each a JSON array (never a string), and each returns what landed:
+- create_surfaces \u2014 add registry rows (saved at once). A row alone does not make a page agent-readable; that needs a code manifest.
+- update_surfaces \u2014 change sort order, executor, and (only on surfaces WITHOUT a code manifest) description, parent, url pattern and active flag. is_active: false deactivates reversibly.
+- new_surface_draft \u2014 fill the New surface dialog for the person to review and save themselves.
+- delete_surfaces \u2014 moves surfaces to Trash (restorable); refused for manifested surfaces. To only hide one, use is_active: false.
+Never change the registry with generic database or context tools: they skip these checks.
+</surface_intro>`,
+  groups,
+  values: mergeBaselineValues(
+    pickBaseline("selection", "context"),
+    surfaceSpecific
+  ),
+  writeTargets
+};
+function createAdminUiSurfacesScope(values) {
+  return values;
+}
+export {
+  ADMIN_UI_SURFACES_SURFACE_NAME,
+  adminUiSurfacesManifest,
+  createAdminUiSurfacesScope
+};