@kortix/ui 0.0.0-stage → 0.14.4

package/dist/customize/shared/catalog/catalog-grid.d.ts

@@ -0,0 +1,53 @@
+import type { ReactNode } from 'react';
+export interface CatalogGridProps {
+    isLoading: boolean;
+    isError: boolean;
+    /** The thrown value, when there is one. Optional so existing callers keep
+     *  working; without it every failure reads as a connection failure, which is
+     *  what `catalogErrorCopy` exists to stop. Pass it. */
+    error?: unknown;
+    onRetry: () => void;
+    isEmpty: boolean;
+    /** Rendered in place of the grid when `isEmpty` is true. The grid does not
+     *  own empty copy — agents, connectors, and skills each know what their
+     *  own "nothing here" invitation should say. */
+    empty: ReactNode;
+    children: ReactNode;
+    /** The All tab's tighter grid (`DENSE_GRID_CLASSNAME`) for `plain` cards. */
+    dense?: boolean;
+}
+/**
+ * One catalog-card placeholder. Mirrors `CatalogCard`'s chrome (bordered
+ * surface, leading tile, title + one description line) so the loading →
+ * content handoff does not jump from a solid grey slab into a card.
+ *
+ * Deliberately sparse — one description bar, not two — so the skeleton reads
+ * calmer than a packed mock of the settled card.
+ *
+ * The height comes from `CATALOG_CARD_HEIGHT_CLASSNAME`, not from the inner
+ * shapes, so the outer box is exactly the real card's 84px no matter how the
+ * inside is composed. It was hardcoded `h-20` (80px) while that token sat
+ * imported-but-unused, which cost 4px of reflow per row on every catalog load.
+ */
+export declare function CatalogCardSkeleton(): import("react").JSX.Element;
+/**
+ * The catalog loading grid shared by `CatalogGrid`, `CapabilitiesSkeleton`,
+ * and every capabilities route. One component — agents, connectors, and
+ * skills never diverge on loading chrome.
+ */
+export declare function CatalogGridSkeleton({ count, }?: {
+    count?: number;
+}): import("react").JSX.Element;
+/**
+ * The one grid shared by the agents, connectors, and skills catalog pages.
+ * Owns the four states in design-system order: loading -> error -> empty ->
+ * content. Callers only supply query state and the content/empty nodes.
+ *
+ * `sm:grid-cols-2 xl:grid-cols-3` (not `lg:grid-cols-3`) is deliberate: at
+ * the `lg` breakpoint (1024-1279px) a 3-up card does not have room for a
+ * title, a description line, and a trailing slot without truncating hard.
+ * Loading chrome is `CatalogGridSkeleton` — the same surface
+ * `capability-skeleton.tsx` paints behind the Suspense boundary — so the
+ * loading-to-content handover never reflows a column or a row.
+ */
+export declare function CatalogGrid({ isLoading, isError, error, onRetry, isEmpty, empty, children, dense, }: CatalogGridProps): import("react").JSX.Element;

package/dist/customize/shared/catalog/catalog-grid.js

@@ -0,0 +1,66 @@
+'use client';
+import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+import { useTranslations } from '../../../i18n/index.js';
+import { Button } from '../../../primitives/button.js';
+import { Skeleton } from '../../../primitives/skeleton.js';
+import { ErrorState } from '../../../primitives/error-state.js';
+import { cn } from '../../../internal/lib/utils.js';
+import { catalogErrorCopy } from './catalog-error.js';
+import { CATALOG_CARD_HEIGHT_CLASSNAME, DENSE_GRID_CLASSNAME, DENSE_GRID_CONTAINER_CLASSNAME, GRID_CLASSNAME, } from './catalog-grid-tokens.js';
+// Layout tokens live in `./catalog-grid-tokens` so this module exports only
+// components and stays on React Fast Refresh's hot path.
+const SKELETON_CARD_COUNT = 6;
+/**
+ * One catalog-card placeholder. Mirrors `CatalogCard`'s chrome (bordered
+ * surface, leading tile, title + one description line) so the loading →
+ * content handoff does not jump from a solid grey slab into a card.
+ *
+ * Deliberately sparse — one description bar, not two — so the skeleton reads
+ * calmer than a packed mock of the settled card.
+ *
+ * The height comes from `CATALOG_CARD_HEIGHT_CLASSNAME`, not from the inner
+ * shapes, so the outer box is exactly the real card's 84px no matter how the
+ * inside is composed. It was hardcoded `h-20` (80px) while that token sat
+ * imported-but-unused, which cost 4px of reflow per row on every catalog load.
+ */
+export function CatalogCardSkeleton() {
+    return (_jsx(Skeleton, { className: cn(CATALOG_CARD_HEIGHT_CLASSNAME), "data-slot": "catalog-card-skeleton" }));
+}
+/**
+ * The catalog loading grid shared by `CatalogGrid`, `CapabilitiesSkeleton`,
+ * and every capabilities route. One component — agents, connectors, and
+ * skills never diverge on loading chrome.
+ */
+export function CatalogGridSkeleton({ count = SKELETON_CARD_COUNT, } = {}) {
+    return (_jsx("div", { className: GRID_CLASSNAME, "data-slot": "catalog-grid-skeleton", children: Array.from({ length: count }, (_, index) => (_jsx(CatalogCardSkeleton, {}, index))) }));
+}
+/**
+ * The one grid shared by the agents, connectors, and skills catalog pages.
+ * Owns the four states in design-system order: loading -> error -> empty ->
+ * content. Callers only supply query state and the content/empty nodes.
+ *
+ * `sm:grid-cols-2 xl:grid-cols-3` (not `lg:grid-cols-3`) is deliberate: at
+ * the `lg` breakpoint (1024-1279px) a 3-up card does not have room for a
+ * title, a description line, and a trailing slot without truncating hard.
+ * Loading chrome is `CatalogGridSkeleton` — the same surface
+ * `capability-skeleton.tsx` paints behind the Suspense boundary — so the
+ * loading-to-content handover never reflows a column or a row.
+ */
+export function CatalogGrid({ isLoading, isError, error, onRetry, isEmpty, empty, children, dense = false, }) {
+    const tI18nComplete = useTranslations('hardcodedUi.i18nComplete');
+    if (isLoading) {
+        return _jsx(CatalogGridSkeleton, {});
+    }
+    if (isError) {
+        // Copy is derived from the failure rather than fixed, because the fixed
+        // string named a cause. See `catalog-error.ts`.
+        const copy = catalogErrorCopy(error, tI18nComplete);
+        return (_jsx(ErrorState, { size: "sm", title: copy.title, description: copy.description, action: copy.canRetry ? (_jsx(Button, { variant: "outline", size: "sm", onClick: onRetry, children: tI18nComplete.raw('text942087cc2d41') })) : undefined }));
+    }
+    if (isEmpty) {
+        return _jsx(_Fragment, { children: empty });
+    }
+    if (dense)
+        return (_jsx("div", { className: DENSE_GRID_CONTAINER_CLASSNAME, children: _jsx("div", { className: DENSE_GRID_CLASSNAME, children: children }) }));
+    return _jsx("div", { className: GRID_CLASSNAME, children: children });
+}

package/dist/customize/shared/detail-selection.d.ts

@@ -0,0 +1,54 @@
+/**
+ * One rule for every capability detail modal: **intent drives `open`, data
+ * drives contents.**
+ *
+ * Every capabilities page had it the other way round —
+ *
+ *   open={records.find((r) => r.id === selection) !== null}
+ *
+ * — which hands the query control of the modal. Two failures come straight out
+ * of that, and both are the "random modal" glitch:
+ *
+ *  1. **It opens itself.** `/connectors?c=slack` is a real entry point: a deep
+ *     link, and the OAuth 2.0 return leg, which is a full page load by design
+ *     (see `connectors-page.tsx` on why `?c=` survives it). On the first
+ *     render the list is still loading, so the lookup misses and the modal is
+ *     shut. The page paints. Then data lands and a modal animates open on its
+ *     own, a beat after the user thought the page had settled.
+ *
+ *  2. **It closes itself.** `invalidate()` refetches four keys on every
+ *     rename, toggle and connect. One failure empties `data`, the lookup
+ *     misses, and a modal the user is working in disappears. Skills and
+ *     commands have the same exposure through a background agent editing
+ *     `kortix.yaml`: a changed `path` is indistinguishable from a deleted one.
+ *
+ * The fix is to keep the two concerns apart. `open` follows the SELECTION,
+ * which only the user changes. The record is content: absent means show a
+ * placeholder, not close. The modal closes for exactly one data-driven reason
+ * — the query SUCCEEDED and the record genuinely is not in it — which is a
+ * real deletion, not a refetch, an error, or a slow first paint.
+ *
+ * `isSuccess` (not `!isLoading`) is what makes that distinction hold: a query
+ * that has exhausted its retries reports `isLoading === false` while `data`
+ * stays undefined, so a `!isLoading` test would read a network failure as a
+ * deletion and close the modal — the exact bug this replaces.
+ */
+export interface DetailSelection<TRecord> {
+    /** True whenever the user has something selected. Drives `open`, alone. */
+    open: boolean;
+    /** The record to render, or `null` while it is still being resolved. */
+    record: TRecord | null;
+    /** Selected, but the record has not arrived yet — render a placeholder. */
+    isResolving: boolean;
+    /** Selected, the query succeeded, and the record is genuinely gone. The
+     *  caller clears the selection on this — the one honest auto-close. */
+    isMissing: boolean;
+}
+export declare function detailSelection<TRecord>(input: {
+    /** What the user picked: a slug, a path, any stable id. `null` = nothing. */
+    selection: string | null;
+    /** The looked-up record, or `null`/`undefined` when not found. */
+    record: TRecord | null | undefined;
+    /** Has the query that owns `record` returned data at least once? */
+    isSuccess: boolean;
+}): DetailSelection<TRecord>;

package/dist/customize/shared/detail-selection.js

@@ -0,0 +1,11 @@
+export function detailSelection(input) {
+    const open = input.selection !== null;
+    const record = input.record ?? null;
+    const unresolved = open && record === null;
+    return {
+        open,
+        record,
+        isResolving: unresolved && !input.isSuccess,
+        isMissing: unresolved && input.isSuccess,
+    };
+}

package/dist/customize/shared/entity/entity-files.d.ts

@@ -0,0 +1,26 @@
+export interface FileNode {
+    name: string;
+    path: string;
+    /** Segments below the entity directory. 0 = sits directly in it. */
+    depth: number;
+}
+/**
+ * The directory a skill/command's own files live under, derived from the
+ * entity's own `path` — never assume a fixed prefix. Real project data uses
+ * `skills/<name>/SKILL.md` (legacy `.kortix/opencode/skills/...`); some fixtures/tests use
+ * `.opencode/skill/<name>/SKILL.md`. Both work because this only looks at
+ * the last `/`, after stripping a manifest anchor (`kortix.yaml#agents.x`)
+ * via `configEntitySourcePath`.
+ */
+export declare function entityDirectory(path: string): string;
+/**
+ * The entity's own files, from a repo listing already scoped to its directory.
+ * SKILL.md sorts first because it is the entry point every reader wants; the
+ * rest sort by path segments (`compareSegments`) so a directory's own files
+ * stay grouped above its subdirectories — see that function's doc comment for
+ * the exact bug this fixes.
+ */
+export declare function buildFileTree(paths: readonly string[], dir: string): FileNode[];
+/** Whether a file renders through `UnifiedMarkdown` rather than a code block. */
+export declare function isMarkdownPath(path: string): boolean;
+export declare function languageForPath(path: string): string;

package/dist/customize/shared/entity/entity-files.js

@@ -0,0 +1,121 @@
+import { configEntitySourcePath } from '../../sections/component/config-entity-source-path.js';
+/**
+ * The directory a skill/command's own files live under, derived from the
+ * entity's own `path` — never assume a fixed prefix. Real project data uses
+ * `skills/<name>/SKILL.md` (legacy `.kortix/opencode/skills/...`); some fixtures/tests use
+ * `.opencode/skill/<name>/SKILL.md`. Both work because this only looks at
+ * the last `/`, after stripping a manifest anchor (`kortix.yaml#agents.x`)
+ * via `configEntitySourcePath`.
+ */
+export function entityDirectory(path) {
+    const source = configEntitySourcePath(path);
+    const cut = source.lastIndexOf('/');
+    return cut === -1 ? '' : source.slice(0, cut);
+}
+/**
+ * Compares two paths' segments below the entity directory so siblings stay
+ * grouped as a real tree, not a flat lexicographic list.
+ *
+ * Sorting the joined path as one string (the original approach here) put
+ * `scripts/templates/comments.xml` ahead of `scripts/unpack.py`, because
+ * `"t" < "u"` — visually wrong: `unpack.py` is a direct sibling of
+ * `accept_changes.py`/`comment.py`/`pack.py`, but rendered outdented beneath
+ * the entire `templates/` folder, reading as orphaned. Comparing segment by
+ * segment fixes it: at the first differing position, a segment that is the
+ * END of its own path (a leaf/file) sorts before one that continues further
+ * (an intermediate directory) — so every file in a directory lists before
+ * that directory's own subdirectories, regardless of alphabetical value.
+ * Otherwise (both leaves, or both intermediate directories at this position)
+ * `localeCompare` that segment.
+ */
+function compareSegments(a, b) {
+    const len = Math.min(a.length, b.length);
+    for (let i = 0; i < len; i++) {
+        if (a[i] === b[i])
+            continue;
+        const aIsLeaf = i === a.length - 1;
+        const bIsLeaf = i === b.length - 1;
+        if (aIsLeaf !== bIsLeaf)
+            return aIsLeaf ? -1 : 1;
+        return a[i].localeCompare(b[i]);
+    }
+    return a.length - b.length;
+}
+/**
+ * The entity's own files, from a repo listing already scoped to its directory.
+ * SKILL.md sorts first because it is the entry point every reader wants; the
+ * rest sort by path segments (`compareSegments`) so a directory's own files
+ * stay grouped above its subdirectories — see that function's doc comment for
+ * the exact bug this fixes.
+ */
+export function buildFileTree(paths, dir) {
+    const prefix = dir ? `${dir}/` : '';
+    const nodes = [];
+    for (const p of paths) {
+        if (dir ? !p.startsWith(prefix) : p.includes('/'))
+            continue;
+        const rel = p.slice(prefix.length);
+        const segments = rel.split('/');
+        nodes.push({
+            path: p,
+            name: segments[segments.length - 1] ?? rel,
+            depth: segments.length - 1,
+            segments,
+        });
+    }
+    nodes.sort((a, b) => {
+        const aEntry = a.name === 'SKILL.md' && a.depth === 0;
+        const bEntry = b.name === 'SKILL.md' && b.depth === 0;
+        if (aEntry !== bEntry)
+            return aEntry ? -1 : 1;
+        return compareSegments(a.segments, b.segments);
+    });
+    return nodes.map(({ path, name, depth }) => ({ path, name, depth }));
+}
+function extensionOf(path) {
+    const base = path.split('/').pop() ?? path;
+    const dot = base.lastIndexOf('.');
+    return dot === -1 ? '' : base.slice(dot + 1).toLowerCase();
+}
+/** Whether a file renders through `UnifiedMarkdown` rather than a code block. */
+export function isMarkdownPath(path) {
+    const ext = extensionOf(path);
+    return ext === 'md' || ext === 'markdown';
+}
+/**
+ * Extension -> the language Shiki should highlight a non-markdown file with.
+ * Mirrors `packages/ui/src/files/viewer/file-viewer.tsx`'s
+ * `LANGUAGE_BY_EXT` (the established convention for feeding `CodeBlockCode` a
+ * raw file's language), extended with a direct `xml` entry — that file only
+ * aliases `svg` to `xml` and has no bare `xml` key, but skill/command
+ * directories carry real `.xml` templates (e.g. the `docx` skill's
+ * `scripts/templates/*.xml`) that need the same highlighting.
+ *
+ * An unknown or missing extension falls back to `'text'` — plain, unstyled
+ * text, never a crash and never a guessed language.
+ */
+const LANGUAGE_BY_EXTENSION = {
+    ts: 'typescript',
+    tsx: 'tsx',
+    js: 'javascript',
+    jsx: 'jsx',
+    json: 'json',
+    py: 'python',
+    rb: 'ruby',
+    go: 'go',
+    rs: 'rust',
+    sh: 'bash',
+    bash: 'bash',
+    yml: 'yaml',
+    yaml: 'yaml',
+    toml: 'toml',
+    css: 'css',
+    html: 'html',
+    htm: 'html',
+    xml: 'xml',
+    svg: 'xml',
+    sql: 'sql',
+};
+export function languageForPath(path) {
+    return LANGUAGE_BY_EXTENSION[extensionOf(path)] ?? 'text';
+}

package/dist/customize/shared/entity/entity-modal.d.ts

@@ -0,0 +1,58 @@
+import { type ReactNode } from 'react';
+export type EntityKind = 'skill' | 'command' | 'agent';
+export interface EntityDetailEntity {
+    name: string;
+    path: string;
+    description: string | null;
+}
+export interface EntityDetailModalProps {
+    projectId: string;
+    /** The skill/command to show, or `null` when it has not resolved yet. `open`
+     *  is driven by the SELECTION, not by this — see
+     *  `shared/detail-selection.ts`. Selecting a different card while `open`
+     *  stays `true` swaps the content in place (no close/reopen). */
+    entity: EntityDetailEntity | null;
+    kind: EntityKind;
+    open: boolean;
+    /** Open on a selection whose record has not arrived. Renders the shell so a
+     *  refetch cannot blank the modal the user is working in. */
+    isResolving?: boolean;
+    /** Optional third column, right of the source pane — the entity's settings.
+     *  Agents put their assignments + configuration cards here; skills and
+     *  commands pass nothing and the modal stays two columns wide. */
+    aside?: ReactNode;
+    /** Status chips rendered inline after the title. Keep these to states worth
+     *  flagging — a chip every entity carries is noise, and the source path
+     *  already renders under the title as its own line. */
+    meta?: ReactNode;
+    /** Replaces the source pane while set — the agent configuration editor
+     *  uses this so editing happens in this same shell (one level deep), not
+     *  in a modal stacked on the modal. Omit for the normal file pane. */
+    paneOverride?: ReactNode;
+    onOpenChange: (open: boolean) => void;
+}
+/**
+ * The skill/command/agent detail modal. Left to right: the file tree (for
+ * directory-owning kinds only), the caller's optional settings `aside`, then
+ * the selected file's source. Controls precede content — you read toward the
+ * source, and the things you act on sit on the edge you start from. One
+ * component for every kind; the differences are the write-permission action
+ * probed and whether a file rail applies (`OWNS_ITS_DIRECTORY`).
+ *
+ * `EntityModalBody` is keyed on `entity.path` so switching cards while the
+ * modal stays open resets its internal file selection instead of carrying
+ * over a path that belongs to the previous entity — without remounting the
+ * `Modal`/`ModalContent` itself, which would replay the open animation and
+ * drop focus trap continuity.
+ */
+export declare function EntityDetailModal({ projectId, entity, kind, open, isResolving, aside, meta, paneOverride, onOpenChange, }: EntityDetailModalProps): import("react").JSX.Element;
+export declare function EntityFilePane({ path, content, isLoading, isError, error, onRetry, errorTitle, skeletonRows, }: {
+    path: string;
+    content: string | undefined;
+    isLoading: boolean;
+    isError: boolean;
+    error: unknown;
+    onRetry: () => void;
+    errorTitle?: string;
+    skeletonRows?: 4 | 5;
+}): import("react").JSX.Element;

package/dist/customize/shared/entity/entity-modal.js

@@ -0,0 +1,144 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useTranslations } from '../../../i18n/index.js';
+import { useMemo, useState } from 'react';
+import { HighlightedCode } from '../../../markdown/code/index.js';
+import { MarkdownWithFrontmatter } from '../../../markdown/markdown-frontmatter.js';
+import { AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogTitle, AlertDialogTrigger, } from '../../../primitives/alert-dialog.js';
+import { Button } from '../../../primitives/button.js';
+import { FileTree, FileTreeNav } from '../../../primitives/file-tree.js';
+import Loading from '../../../primitives/loading.js';
+import { Modal, ModalBody, ModalContent, ModalHeader, ModalTitle } from '../../../primitives/modal.js';
+import { Skeleton } from '../../../primitives/skeleton.js';
+import { ErrorState } from '../../../primitives/error-state.js';
+import { configEntitySourcePath } from '../../sections/component/config-entity-source-path.js';
+import { editConfigPrompt, useConfigureThread, } from '../../use-configure-thread.js';
+import { PROJECT_ACTIONS } from '../../../internal/lib/project-actions.js';
+import { useProjectCan } from '../../../internal/lib/use-project-can.js';
+import { cn } from '../../../internal/lib/utils.js';
+import { listProjectFiles, readProjectFile } from '@kortix/sdk';
+import { useProjectAccountId } from '@kortix/sdk/react';
+import { PencilSimpleIcon } from '@phosphor-icons/react';
+import { useQuery } from '@tanstack/react-query';
+import { FadedScrollArea } from '../../../primitives/faded-scroll-area.js';
+import { buildFileTree, entityDirectory, isMarkdownPath, languageForPath } from './entity-files.js';
+const WRITE_ACTION = {
+    skill: PROJECT_ACTIONS.PROJECT_SKILL_WRITE,
+    command: PROJECT_ACTIONS.PROJECT_COMMAND_WRITE,
+    agent: PROJECT_ACTIONS.PROJECT_AGENT_WRITE,
+};
+/**
+ * Whether listing the entity's directory lists THAT ENTITY's files.
+ *
+ * A skill owns its directory — `skills/<name>/SKILL.md` plus
+ * its own scripts and templates — so the listing is exactly its file tree.
+ * An agent is a single file in a SHARED directory
+ * (`agents/<name>.md`), so the same listing returns every
+ * other agent in the project. Rendering that as "this agent's files" would let
+ * a click swap the source pane to a different agent while the modal title,
+ * the badges, and the configuration aside all still describe the first one.
+ *
+ * Single-file kinds therefore drop the file rail entirely: the modal is the
+ * entity's own source plus whatever `aside` the caller supplies.
+ */
+const OWNS_ITS_DIRECTORY = {
+    skill: true,
+    command: true,
+    agent: false,
+};
+/**
+ * The skill/command/agent detail modal. Left to right: the file tree (for
+ * directory-owning kinds only), the caller's optional settings `aside`, then
+ * the selected file's source. Controls precede content — you read toward the
+ * source, and the things you act on sit on the edge you start from. One
+ * component for every kind; the differences are the write-permission action
+ * probed and whether a file rail applies (`OWNS_ITS_DIRECTORY`).
+ *
+ * `EntityModalBody` is keyed on `entity.path` so switching cards while the
+ * modal stays open resets its internal file selection instead of carrying
+ * over a path that belongs to the previous entity — without remounting the
+ * `Modal`/`ModalContent` itself, which would replay the open animation and
+ * drop focus trap continuity.
+ */
+export function EntityDetailModal({ projectId, entity, kind, open, isResolving = false, aside, meta, paneOverride, onOpenChange, }) {
+    // A skill/command with no description renders no `ModalDescription`, so
+    // Radix's Dialog can't find one to auto-associate via `aria-describedby`
+    // and logs a dev-only "Missing Description" warning. Passing
+    // `aria-describedby={undefined}` explicitly (as its own prop key, not just
+    // omitting the attribute) is Radix's documented opt-out — the warning
+    // message itself names this exact fix. Only applied when there truly is no
+    // description; when one exists, `ModalDescription` wires up normally.
+    const suppressDescriptionWarning = !entity?.description;
+    return (_jsx(Modal, { open: open, onOpenChange: onOpenChange, children: _jsx(ModalContent, { className: "bg-popover space-y-0 lg:max-w-6xl", ...(suppressDescriptionWarning ? { 'aria-describedby': undefined } : {}), children: entity ? (_jsx(EntityModalBody, { projectId: projectId, entity: entity, kind: kind, aside: aside, meta: meta, paneOverride: paneOverride }, entity.path)) : isResolving ? (_jsx(EntityModalSkeleton, { kind: kind })) : null }) }));
+}
+/**
+ * The shell, while the selected path is being resolved against a config that
+ * has not arrived. Shape-matched to `EntityModalBody` — same header, same
+ * `lg:w-64` file rail — so the handover fills placeholders in place.
+ *
+ * `ModalTitle` is real, not decorative: Radix's Dialog requires an accessible
+ * name for the whole time it is open, including this window.
+ */
+function EntityModalSkeleton({ kind }) {
+    const tI18nComplete = useTranslations('hardcodedUi.i18nComplete');
+    return (_jsxs(_Fragment, { children: [_jsxs(ModalHeader, { className: "border-border/60 space-y-1 border-b pb-4", children: [_jsxs(ModalTitle, { className: "sr-only", children: [tI18nComplete.raw('textdc380888c4e2'), " ", kind] }), _jsx(Skeleton, { className: "h-5 w-48 rounded-sm", "aria-hidden": true })] }), _jsx(ModalBody, { className: "max-h-[70vh] overflow-hidden p-0", children: _jsxs("div", { className: "flex min-h-0 flex-col lg:h-[70vh] lg:flex-row", children: [OWNS_ITS_DIRECTORY[kind] ? (_jsx("div", { className: "border-border/60 shrink-0 space-y-1.5 border-b p-2 lg:h-full lg:w-64 lg:border-r lg:border-b-0", children: [0, 1, 2].map((i) => (_jsx(Skeleton, { className: "h-7 w-full rounded-md" }, i))) })) : null, _jsxs("div", { className: "min-w-0 flex-1 space-y-3 p-4", children: [_jsx(Skeleton, { className: "h-4 w-32 rounded-sm" }), _jsx(Skeleton, { className: "h-40 w-full rounded-md" })] })] }) })] }));
+}
+function EntityModalBody({ projectId, entity, kind, aside, meta, paneOverride, }) {
+    const tI18nComplete = useTranslations('hardcodedUi.i18nComplete');
+    const configure = useConfigureThread(projectId);
+    // `accountId` skips useProjectCan's own getProject and lets the IAM probe
+    // run on the first render instead of waiting a round-trip for it.
+    const accountId = useProjectAccountId(projectId);
+    const canWrite = useProjectCan(projectId, WRITE_ACTION[kind], { accountId }).allowed === true;
+    // The real repo path, with any manifest anchor stripped. Agents declared in
+    // the manifest rather than as their own file carry one
+    // (`kortix.yaml#agents.<name>`), and reading that verbatim is a 404 — the
+    // source is `kortix.yaml` itself, which then renders as highlighted YAML
+    // because `isMarkdownPath` is false for it. Skills and commands do not carry
+    // an anchor in practice. Every file read and the tree's own paths are
+    // relative to this.
+    const sourcePath = configEntitySourcePath(entity.path);
+    const dir = entityDirectory(entity.path);
+    const hasFileRail = OWNS_ITS_DIRECTORY[kind];
+    const [selectedPath, setSelectedPath] = useState(sourcePath);
+    // Not fetched at all for a single-file kind: the listing would be every
+    // sibling entity's source, and nothing renders it (see OWNS_ITS_DIRECTORY).
+    const filesQuery = useQuery({
+        queryKey: ['entity-files', projectId, dir],
+        queryFn: () => listProjectFiles(projectId, { path: dir }),
+        enabled: hasFileRail && dir !== '',
+        staleTime: 30_000,
+    });
+    const nodes = useMemo(() => buildFileTree(filesQuery.data?.map((f) => f.path) ?? [], dir), [filesQuery.data, dir]);
+    const fileQuery = useQuery({
+        queryKey: ['entity-file-content', projectId, selectedPath],
+        queryFn: () => readProjectFile(projectId, selectedPath),
+        staleTime: 30_000,
+    });
+    // The one write affordance, placed by layout: at the foot of the file rail
+    // when there is one, otherwise at the top of the settings aside. Built once
+    // so the two placements cannot drift into two different controls.
+    //
+    // The click does not send the prompt directly — `configure.start` opens a
+    // whole new chat, which is a bigger commitment than a pencil icon implies,
+    // so an AlertDialog confirms first. The dialog nests inside this modal's
+    // React tree on purpose: rendered as a sibling, Radix would read every
+    // click in the alert as an outside-click and dismiss the modal underneath
+    // (see packages/ui/src/primitives/alert-dialog.tsx).
+    const editButton = canWrite ? (_jsx(EntityEditButton, { name: entity.name, pending: configure.pending, onEdit: () => configure.start(editConfigPrompt(kind, entity.name, entity.path)) })) : null;
+    // The aside earns its column when it holds something: the caller's settings,
+    // or — for a single-file kind, which has no rail to host it — the edit
+    // action. Without this an agent modal viewed by a reader with no write
+    // permission would render an empty 320px column.
+    const showAside = Boolean(aside) || (!hasFileRail && editButton !== null);
+    const fileRail = (_jsxs("div", { className: "border-border/60 flex shrink-0 flex-col border-b p-2 lg:h-full lg:w-64 lg:overflow-hidden lg:border-r lg:border-b-0", children: [_jsxs(FadedScrollArea, { fadeColor: "from-popover", rootClassName: "h-auto min-h-0 flex-1", className: "overscroll-contain", children: [_jsx(FileTree, { title: tI18nComplete.raw('textabc7e9892806'), children: _jsx(FileTreeNav, { nodes: nodes, selectedPath: selectedPath, onSelect: setSelectedPath, label: `${entity.name} files` }) }), filesQuery.isError ? (_jsxs("p", { className: "text-muted-foreground mt-4 text-xs text-pretty", children: [tI18nComplete.raw('text881c0bd6449b'), ' ', _jsx("button", { type: "button", onClick: () => void filesQuery.refetch(), className: "text-foreground underline underline-offset-2", children: tI18nComplete.raw('text942087cc2d41') })] })) : null] }), editButton ? _jsx("div", { className: "shrink-0 pt-4", children: editButton }) : null] }));
+    return (_jsxs(_Fragment, { children: [_jsx(ModalHeader, { className: "border-border/60 space-y-1 border-b pr-10 pb-4", children: _jsxs("div", { className: "flex flex-wrap items-center gap-x-2 gap-y-1", children: [_jsx(ModalTitle, { className: "min-w-0 truncate", children: entity.name }), meta] }) }), _jsx(ModalBody, { className: "max-h-[70vh] overflow-hidden p-0", children: _jsxs("div", { className: "flex min-h-0 flex-col overflow-y-auto lg:h-[70vh] lg:flex-row lg:overflow-hidden", children: [hasFileRail ? fileRail : null, showAside ? (_jsxs("aside", { className: "border-border/60 flex h-full min-h-0 shrink-0 flex-col justify-between space-y-3 border-b p-4 lg:h-full lg:min-h-0 lg:w-80 lg:overflow-y-auto lg:border-r lg:border-b-0", children: [aside, _jsx("div", { className: "mt-auto pt-4", children: hasFileRail ? null : editButton })] })) : null, _jsx("div", { className: cn('bg-popover min-w-0 flex-1 overflow-hidden', paneOverride ? 'flex flex-col' : 'overflow-y-auto'), children: paneOverride ?? (_jsx(EntityFilePane, { path: selectedPath, content: fileQuery.data?.content, isLoading: fileQuery.isLoading, isError: fileQuery.isError, error: fileQuery.error, onRetry: () => fileQuery.refetch() }, selectedPath)) })] }) })] }));
+}
+export function EntityFilePane({ path, content, isLoading, isError, error, onRetry, errorTitle, skeletonRows = 5, }) {
+    const tI18nComplete = useTranslations('hardcodedUi.i18nComplete');
+    return (_jsx(_Fragment, { children: isLoading ? (_jsxs("div", { className: "space-y-2.5 p-4", children: [_jsx(Skeleton, { className: "h-4 w-full" }), _jsx(Skeleton, { className: "h-4 w-11/12" }), _jsx(Skeleton, { className: "h-4 w-10/12" }), _jsx(Skeleton, { className: "h-4 w-9/12" }), skeletonRows === 5 ? _jsx(Skeleton, { className: "h-4 w-full" }) : null] })) : isError ? (_jsx("div", { className: "p-4", children: _jsx(ErrorState, { size: "sm", title: errorTitle ?? tI18nComplete.raw('textf27a58a42762'), description: error instanceof Error ? error.message : tI18nComplete.raw('text553d1ec7c9e6'), action: _jsx(Button, { variant: "outline", size: "sm", onClick: onRetry, children: tI18nComplete.raw('text942087cc2d41') }) }) })) : isMarkdownPath(path) ? (_jsx("div", { className: "p-4", children: _jsx(MarkdownWithFrontmatter, { content: content ?? '', documentPath: path }) })) : (_jsx("pre", { className: cn('overflow-x-auto p-4', 'text-foreground font-mono text-sm leading-[1.65]', '[&_code]:border-none [&_code]:bg-transparent [&_code]:p-0 [&_code]:text-inherit', '[&_.shiki]:!bg-transparent [&_span]:border-none [&_span]:!bg-transparent [&_span]:outline-none'), children: _jsx(HighlightedCode, { code: content ?? '', language: languageForPath(path) }) })) }));
+}
+function EntityEditButton({ name, pending, onEdit, }) {
+    const tI18nComplete = useTranslations('hardcodedUi.i18nComplete');
+    return (_jsxs(AlertDialog, { children: [_jsx(AlertDialogTrigger, { asChild: true, children: _jsxs(Button, { variant: "secondary", size: "sm", className: "w-full justify-start border", disabled: pending, children: [pending ? (_jsx(Loading, { className: "text-foreground size-3.5 shrink-0" })) : (_jsx(PencilSimpleIcon, { className: "size-3.5 shrink-0" })), tI18nComplete.raw('text4314a9413ab7')] }) }), _jsxs(AlertDialogContent, { children: [_jsxs(AlertDialogHeader, { children: [_jsx(AlertDialogTitle, { children: tI18nComplete.raw('textdc0a04e35f6e') }), _jsxs(AlertDialogDescription, { children: [tI18nComplete.raw('text60c72685917f'), " ", name, tI18nComplete.raw('text412cc9a16edd')] })] }), _jsxs(AlertDialogFooter, { children: [_jsx(AlertDialogCancel, { children: tI18nComplete.raw('text19766ed6ccb2') }), _jsx(AlertDialogAction, { onClick: () => onEdit(), children: tI18nComplete.raw('textf6f4688ff23d') })] })] })] }));
+}

package/dist/customize/shared/feature-gate-screen.d.ts

@@ -0,0 +1,11 @@
+import { type FeatureFlagKey } from '@kortix/sdk';
+/** A disabled surface keeps its enable action and settings link in place. */
+export declare function FeatureGateScreen({ featureKey, featureName, description, internalOnly, }: {
+    featureKey: FeatureFlagKey;
+    /** The feature's name, exactly as the Feature flags section lists it. */
+    featureName: string;
+    /** One sentence: what turning it on would give this project. */
+    description: string;
+    /** The flag is not offered in Settings (`catalogHidden`): no button, ask Kortix instead. */
+    internalOnly?: boolean;
+}): import("react").JSX.Element;

package/dist/customize/shared/feature-gate-screen.js

@@ -0,0 +1,44 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useTranslations } from '../../i18n/index.js';
+import { UiLink, useUiParams } from '../../providers/ui-provider.js';
+import { Button } from '../../primitives/button.js';
+import { projectSettingsSectionHref } from '../project-settings/project-settings-sections.js';
+import { PROJECT_ACTIONS } from '../../internal/lib/project-actions.js';
+import { useProjectCan } from '../../internal/lib/use-project-can.js';
+import { updateFeatureFlag } from '@kortix/sdk';
+import { invalidateProject, qk } from '@kortix/sdk/react';
+import { FlagIcon } from '@phosphor-icons/react';
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+import { useState } from 'react';
+/** A disabled surface keeps its enable action and settings link in place. */
+export function FeatureGateScreen({ featureKey, featureName, description, internalOnly = false, }) {
+    const t = useTranslations('featureGate');
+    const tI18nComplete = useTranslations('hardcodedUi.i18nComplete');
+    const params = useUiParams();
+    const projectId = typeof params.id === 'string' ? params.id : undefined;
+    const queryClient = useQueryClient();
+    const permission = useProjectCan(projectId, PROJECT_ACTIONS.PROJECT_SETTINGS_WRITE);
+    const [error, setError] = useState('');
+    const enable = useMutation({
+        mutationFn: () => {
+            if (!projectId || internalOnly || permission.isLoading || permission.allowed !== true) {
+                throw new Error('Feature activation is not permitted');
+            }
+            return updateFeatureFlag(projectId, featureKey, true);
+        },
+        onSuccess: (updated) => {
+            if (!projectId)
+                return;
+            queryClient.setQueryData(qk.project.summary(projectId), updated);
+            queryClient.setQueryData(qk.project.detail(projectId), (current) => current ? { ...current, project: updated } : current);
+            void invalidateProject(queryClient, projectId);
+            void queryClient.invalidateQueries({ queryKey: qk.projects.scope() });
+        },
+        onError: (cause) => setError(cause.message),
+    });
+    return (_jsx("div", { className: "bg-popover rounded-md border px-4 py-5", children: _jsxs("div", { className: "flex flex-col gap-5 sm:flex-row sm:items-center sm:justify-between", children: [_jsxs("div", { className: "flex min-w-0 items-start gap-3", children: [_jsx("span", { className: "bg-muted/50 flex size-9 shrink-0 items-center justify-center rounded-sm", children: _jsx(FlagIcon, { className: "text-muted-foreground size-5" }) }), _jsxs("div", { className: "min-w-0 space-y-1", children: [_jsxs("p", { className: "text-foreground text-sm font-medium", children: [featureName, " ", tI18nComplete.raw('text26965989cce5')] }), _jsx("p", { className: "text-muted-foreground max-w-xl text-xs text-pretty", children: description }), internalOnly ? (_jsx("p", { className: "text-muted-foreground max-w-xl text-xs text-pretty", children: tI18nComplete.raw('text1c41abcc2fff') })) : null] })] }), error ? (_jsx("p", { role: "alert", className: "text-destructive text-xs", children: error })) : null, projectId && !internalOnly ? (_jsxs("div", { className: "flex shrink-0 items-center gap-2", children: [_jsx(Button, { size: "sm", disabled: permission.isLoading || permission.allowed !== true || enable.isPending, onClick: () => {
+                                setError('');
+                                enable.mutate();
+                            }, children: enable.isPending ? t('enabling') : t('enable', { name: featureName }) }), _jsx(Button, { asChild: true, size: "sm", variant: "secondary", className: "shrink-0", children: _jsx(UiLink, { href: projectSettingsSectionHref(projectId, 'feature-flags'), children: tI18nComplete.raw('text20a2e59ba129') }) })] })) : null] }) }));
+}