@kortix/ui 0.14.3 → 0.14.5

package/dist/customize/connectors/tools/tool-groups.js

@@ -0,0 +1,55 @@
+/**
+ * Two buckets, because that is the only distinction a non-technical reader
+ * needs before granting access: can this look at my data, or change it.
+ * `destructive` folds into writes — a delete is a write with worse consequences,
+ * and a third bucket would just make the safe/unsafe line harder to see.
+ *
+ * An empty bucket is omitted rather than rendered as a heading over nothing.
+ * Input order is kept inside each bucket: that is the order the connector
+ * reports its tools in, which is the order its own docs use.
+ */
+export function groupToolsByRisk(actions, tI18nComplete) {
+    const read = actions.filter((a) => a.risk === 'read');
+    const write = actions.filter((a) => a.risk !== 'read');
+    const groups = [];
+    if (read.length)
+        groups.push({ key: 'read', label: tI18nComplete.raw('textdd28b5cb26fd'), actions: read });
+    if (write.length)
+        groups.push({ key: 'write', label: tI18nComplete.raw('texted26c1af81cf'), actions: write });
+    return groups;
+}
+/**
+ * What one row prints, with nothing said twice.
+ *
+ * An OpenAPI connector commonly derives both `name` and `description` from the
+ * same `summary` — the live `petstore` fixture does for all 19 of its tools —
+ * so a naive row renders "Deletes a pet." over "Deletes a pet." The path is
+ * dropped the same way when the connector never gave the tool a real name.
+ */
+export function toolRowText(action) {
+    const name = action.name?.trim();
+    const description = action.description?.trim();
+    const title = name || action.path;
+    const same = (value) => Boolean(value) && value.toLowerCase() === title.toLowerCase();
+    return {
+        title,
+        path: title === action.path ? null : action.path,
+        description: !description || same(description) ? null : description,
+    };
+}
+/**
+ * Narrow a tool list by a free-text query. A connector with 60 tools is
+ * unusable without one.
+ *
+ * Matches the path, the display name and the description, because a reader
+ * looking for "the one that sends mail" knows the words in the description
+ * long before they know `messages.send`. An all-whitespace query is not a
+ * query — returning nothing for a stray space would read as "this connector
+ * has no tools", which is a different and much worse claim.
+ */
+export function filterActions(actions, query) {
+    const needle = query.trim().toLowerCase();
+    if (!needle)
+        return [...actions];
+    return actions.filter((a) => `${a.path} ${a.name} ${a.description ?? ''}`.toLowerCase().includes(needle));
+}

package/dist/customize/connectors/tools/tool-policy-control.d.ts

@@ -0,0 +1,30 @@
+import type { PolicyChoice } from './tool-policy.js';
+export interface ToolPolicyControlProps {
+    value: PolicyChoice;
+    /** Never fires for the already-selected segment — a re-press is not a write. */
+    onChange: (choice: PolicyChoice) => void;
+    /** Names the group for a screen reader, e.g. `Permission for send_email`. */
+    label: string;
+    /** A write is in flight, or the caller may not write. */
+    disabled?: boolean;
+    /** Set when a project rule decides this tool: disables the group and says why. */
+    lockedReason?: string;
+    /** Shown while `value` is `'default'` — what following the default DOES. */
+    defaultHint?: string;
+}
+/**
+ * The per-tool decision: four segments, four states, every one reachable in
+ * both directions.
+ *
+ * `'default'` presses its own segment and a `Hint` names what the default
+ * actually does, because "Default" alone does not tell a reader whether the
+ * tool runs or asks.
+ *
+ * `transition-[…,scale]`, not `transition-transform`: Tailwind v4's `scale-*`
+ * utility sets the standalone `scale` property, which
+ * `transition-property: transform` does not cover — the press would snap. The
+ * explicit list also replaces `Button`'s base `transition-all`
+ * (`button.tsx:8`), which the polish rules treat as a defect. Same override,
+ * same reason, as `project-icon-field.tsx:217`.
+ */
+export declare function ToolPolicyControl({ value, onChange, label, disabled, lockedReason, defaultHint, }: ToolPolicyControlProps): import("react").JSX.Element;

package/dist/customize/connectors/tools/tool-policy-control.js

@@ -0,0 +1,47 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Button } from '../../../primitives/button.js';
+import { ButtonGroup } from '../../../primitives/button-group.js';
+import Hint from '../../../primitives/hint.js';
+import { cn } from '../../../internal/lib/utils.js';
+import { useLocalizedUiCatalog } from '../../../i18n/ui-catalog/use-localized-ui-catalog.js';
+import { POLICY_SEGMENTS } from './tool-policy-labels.js';
+/**
+ * The per-tool decision: four segments, four states, every one reachable in
+ * both directions.
+ *
+ * `'default'` presses its own segment and a `Hint` names what the default
+ * actually does, because "Default" alone does not tell a reader whether the
+ * tool runs or asks.
+ *
+ * `transition-[…,scale]`, not `transition-transform`: Tailwind v4's `scale-*`
+ * utility sets the standalone `scale` property, which
+ * `transition-property: transform` does not cover — the press would snap. The
+ * explicit list also replaces `Button`'s base `transition-all`
+ * (`button.tsx:8`), which the polish rules treat as a defect. Same override,
+ * same reason, as `project-icon-field.tsx:217`.
+ */
+export function ToolPolicyControl({ value, onChange, label, disabled = false, lockedReason, defaultHint, }) {
+    const policySegments = useLocalizedUiCatalog(POLICY_SEGMENTS);
+    const locked = Boolean(lockedReason);
+    const group = (_jsx(ButtonGroup, { "aria-label": label, className: "shrink-0", children: policySegments.map((segment) => {
+            const selected = value === segment.choice;
+            return (_jsx(Button, { type: "button", size: "sm", variant: selected ? 'secondary-outline' : 'outline', "aria-pressed": selected, disabled: disabled || locked, 
+                // Re-pressing the current choice is a no-op, not a redundant PUT
+                // that rewrites the rule set to what it already is.
+                onClick: () => {
+                    if (!selected)
+                        onChange(segment.choice);
+                }, className: cn('px-2.5 text-xs font-medium', 'transition-[color,background-color,scale] duration-150 active:scale-[0.96]', selected ? segment.tint : cn('text-muted-foreground', segment.hoverTint)), children: segment.label }, segment.choice));
+        }) }));
+    // A disabled control with no explanation is a dead end. The segments carry
+    // `disabled:pointer-events-none`, so the pointer reaches this wrapper and the
+    // tooltip still opens on a locked row.
+    if (lockedReason) {
+        return (_jsx(Hint, { label: lockedReason, side: "bottom", children: _jsx("div", { className: "shrink-0", children: group }) }));
+    }
+    if (value === 'default' && defaultHint) {
+        return (_jsx(Hint, { label: defaultHint, side: "bottom", children: _jsx("div", { className: "shrink-0", children: group }) }));
+    }
+    return group;
+}

package/dist/customize/connectors/tools/tool-policy-labels.d.ts

@@ -0,0 +1,30 @@
+import type { PolicyChoice } from './tool-policy.js';
+/**
+ * The four permission segments and their labels.
+ *
+ * A `.ts` sibling of `tool-policy-control.tsx` rather than two more exports on
+ * it: React Fast Refresh only hot-swaps a module whose every export is a
+ * component, so these constants sitting beside `ToolPolicyControl` made every
+ * edit to the control reload the whole page. `connector-tools.tsx` reads them
+ * too, and now does so without pulling the control's component graph.
+ */
+export interface PolicySegment {
+    choice: PolicyChoice;
+    label: string;
+    /** Applied when the segment is the current choice. */
+    tint: string;
+    /** Previewed on hover, so an unselected control is not a four-colour smear. */
+    hoverTint: string;
+}
+/**
+ * Default · Block · Ask · Allow.
+ *
+ * FOUR segments, because there are genuinely four states. Default sits first
+ * because it is the state every tool starts in, and because the remaining three
+ * then read left-to-right as a trust dial: least on the left, most on the right.
+ *
+ * Default carries no tint. Inheriting is not a decision, and colouring it would
+ * put a fourth hue in every row of a 60-tool connector.
+ */
+export declare const POLICY_SEGMENTS: readonly PolicySegment[];
+export declare const POLICY_CHOICE_LABEL: Record<PolicyChoice, string>;

package/dist/customize/connectors/tools/tool-policy-labels.js

@@ -0,0 +1,42 @@
+/**
+ * Default · Block · Ask · Allow.
+ *
+ * FOUR segments, because there are genuinely four states. Default sits first
+ * because it is the state every tool starts in, and because the remaining three
+ * then read left-to-right as a trust dial: least on the left, most on the right.
+ *
+ * Default carries no tint. Inheriting is not a decision, and colouring it would
+ * put a fourth hue in every row of a 60-tool connector.
+ */
+export const POLICY_SEGMENTS = [
+    {
+        choice: 'default',
+        label: 'Default',
+        tint: 'text-muted-foreground',
+        hoverTint: 'hover:text-foreground',
+    },
+    {
+        choice: 'block',
+        label: 'Block',
+        tint: 'text-destructive',
+        hoverTint: 'hover:text-destructive',
+    },
+    {
+        choice: 'require_approval',
+        label: 'Ask',
+        tint: 'text-kortix-yellow',
+        hoverTint: 'hover:text-kortix-yellow',
+    },
+    {
+        choice: 'always_run',
+        label: 'Allow',
+        tint: 'text-kortix-green',
+        hoverTint: 'hover:text-kortix-green',
+    },
+];
+export const POLICY_CHOICE_LABEL = {
+    default: 'Default',
+    block: 'Block',
+    require_approval: 'Ask',
+    always_run: 'Allow',
+};

package/dist/customize/connectors/tools/tool-policy.d.ts

@@ -0,0 +1,83 @@
+import type { ConnectorEffectivePolicy, ConnectorPolicyAction, ConnectorPolicyRule } from '@kortix/sdk';
+export type PolicyChoice = 'default' | ConnectorPolicyAction;
+/**
+ * What the control should read for a tool. `risk_default` and `allow_all` are
+ * the platform deciding, not the user — showing them as an explicit Allow would
+ * claim a choice nobody made, and hide that changing the default moves them.
+ */
+export declare function effectiveChoice(path: string, effective: readonly ConnectorEffectivePolicy[]): PolicyChoice;
+/**
+ * Project-scope rules are evaluated first and win
+ * (`resolveEffectiveAction`, apps/api/src/connectors/policy.ts:342). Editing the
+ * connector-scope rule under one would change nothing, so the control is
+ * disabled and says where the rule actually lives.
+ */
+export declare function isLockedByProject(path: string, effective: readonly ConnectorEffectivePolicy[]): boolean;
+/**
+ * Apply one choice to a set of exact tool paths. Pattern rules (`*`, `/re/`)
+ * are left untouched: they are a different, coarser instrument, and silently
+ * dropping one while the user clicked a group header would be a data loss.
+ *
+ * `'default'` DELETES the tools' exact rules rather than writing one, which is
+ * what returning a tool to the connector default means and what the shipped
+ * picker did (`connectors-view.tsx:3128`). Without it a tool could be set and
+ * never unset.
+ *
+ * Replacement is case-INSENSITIVE, because that is how the engine matches: it
+ * compiles every glob with the `i` flag (`globToRegex`,
+ * apps/api/src/connectors/policy.ts:69), so a rule written `GetPetById` already
+ * governs `getpetbyid`. De-duping on exact string equality would leave that
+ * rule sitting in front of the new one, dead behind it.
+ *
+ * The result is a SET of rules, not a wire payload — run it through
+ * `orderPolicyRules` before sending, because the runtime is first-match-wins.
+ */
+export declare function applyBulkPolicy(rules: readonly ConnectorPolicyRule[], paths: readonly string[], choice: PolicyChoice): ConnectorPolicyRule[];
+/**
+ * Is this matcher a pattern rather than one exact tool path?
+ *
+ * Same grammar the engine compiles (`compileMatcher`,
+ * apps/api/src/connectors/policy.ts:92): a glob if it contains `*`, or an
+ * explicit regex when slash-wrapped. Everything else is a literal path.
+ */
+export declare function isPatternRule(match: string): boolean;
+/**
+ * Order a rule set for the wire.
+ *
+ * The runtime takes the FIRST matching rule
+ * (`resolveEffectiveAction` -> `firstMatchOrNull`, connectors/policy.ts), so a
+ * `*` rule ahead of an exact rule makes that exact rule dead: the user clicks
+ * Block on one tool, the request succeeds, and nothing changes. Exact rules
+ * therefore go first, patterns after — the same order the shipped panel wrote
+ * (`connectors-view.tsx:3106`). Order within each class is preserved, because
+ * two overlapping patterns still resolve by authoring order.
+ */
+export declare function orderPolicyRules(rules: readonly ConnectorPolicyRule[]): ConnectorPolicyRule[];
+/**
+ * The choice to render for one tool.
+ *
+ * `effective` is the server resolving every scope through the same function
+ * the call gate uses, so it is preferred whenever it covers the tool. It does
+ * not always: a connector that exists only in kortix.yaml with no materialized
+ * row comes back with `effective: []`
+ * (apps/api/src/connectors/db-deps.ts:1151), and older servers omit the field
+ * entirely. Falling back to the stored exact rule keeps the control live in
+ * both cases instead of showing every tool as unset.
+ */
+export declare function toolChoice(path: string, policies: readonly ConnectorPolicyRule[], effective: readonly ConnectorEffectivePolicy[]): PolicyChoice;
+/**
+ * What `effective` will look like once the server applies this change — used
+ * to keep an optimistic update honest.
+ *
+ * Without it the control would snap back to the old value between the click
+ * and the refetch, because the row reads `effective`, not `policies`. A
+ * project-scope entry is left alone: the server would not move it either, and
+ * those rows are disabled anyway.
+ *
+ * `'default'` DROPS the entry instead of guessing a replacement action. What
+ * the tool falls back to — a surviving glob, the risk default, `allow_all` —
+ * is the engine's decision, and inventing one here would put a value on screen
+ * the server never said. `toolChoice` reads `'default'` from the absence, so
+ * the control lands on Default immediately and the refetch fills in the truth.
+ */
+export declare function previewEffective(effective: readonly ConnectorEffectivePolicy[], paths: readonly string[], choice: PolicyChoice): ConnectorEffectivePolicy[];

package/dist/customize/connectors/tools/tool-policy.js

@@ -0,0 +1,116 @@
+/**
+ * What the control should read for a tool. `risk_default` and `allow_all` are
+ * the platform deciding, not the user — showing them as an explicit Allow would
+ * claim a choice nobody made, and hide that changing the default moves them.
+ */
+export function effectiveChoice(path, effective) {
+    const hit = effective.find((e) => e.path === path);
+    if (!hit)
+        return 'default';
+    return hit.source === 'connector' || hit.source === 'project' ? hit.action : 'default';
+}
+/**
+ * Project-scope rules are evaluated first and win
+ * (`resolveEffectiveAction`, apps/api/src/connectors/policy.ts:342). Editing the
+ * connector-scope rule under one would change nothing, so the control is
+ * disabled and says where the rule actually lives.
+ */
+export function isLockedByProject(path, effective) {
+    return effective.find((e) => e.path === path)?.source === 'project';
+}
+/**
+ * Apply one choice to a set of exact tool paths. Pattern rules (`*`, `/re/`)
+ * are left untouched: they are a different, coarser instrument, and silently
+ * dropping one while the user clicked a group header would be a data loss.
+ *
+ * `'default'` DELETES the tools' exact rules rather than writing one, which is
+ * what returning a tool to the connector default means and what the shipped
+ * picker did (`connectors-view.tsx:3128`). Without it a tool could be set and
+ * never unset.
+ *
+ * Replacement is case-INSENSITIVE, because that is how the engine matches: it
+ * compiles every glob with the `i` flag (`globToRegex`,
+ * apps/api/src/connectors/policy.ts:69), so a rule written `GetPetById` already
+ * governs `getpetbyid`. De-duping on exact string equality would leave that
+ * rule sitting in front of the new one, dead behind it.
+ *
+ * The result is a SET of rules, not a wire payload — run it through
+ * `orderPolicyRules` before sending, because the runtime is first-match-wins.
+ */
+export function applyBulkPolicy(rules, paths, choice) {
+    const targets = new Set(paths.map((path) => path.toLowerCase()));
+    // Only an exact rule can name one tool. A glob is never replaced by a
+    // per-tool decision, even when it happens to cover the same tool.
+    const kept = rules.filter((r) => isPatternRule(r.match) || !targets.has(r.match.toLowerCase()));
+    if (choice === 'default')
+        return kept;
+    return [...kept, ...paths.map((match) => ({ match, action: choice }))];
+}
+/**
+ * Is this matcher a pattern rather than one exact tool path?
+ *
+ * Same grammar the engine compiles (`compileMatcher`,
+ * apps/api/src/connectors/policy.ts:92): a glob if it contains `*`, or an
+ * explicit regex when slash-wrapped. Everything else is a literal path.
+ */
+export function isPatternRule(match) {
+    return match.includes('*') || /^\/.*\/[a-z]*$/.test(match);
+}
+/**
+ * Order a rule set for the wire.
+ *
+ * The runtime takes the FIRST matching rule
+ * (`resolveEffectiveAction` -> `firstMatchOrNull`, connectors/policy.ts), so a
+ * `*` rule ahead of an exact rule makes that exact rule dead: the user clicks
+ * Block on one tool, the request succeeds, and nothing changes. Exact rules
+ * therefore go first, patterns after — the same order the shipped panel wrote
+ * (`connectors-view.tsx:3106`). Order within each class is preserved, because
+ * two overlapping patterns still resolve by authoring order.
+ */
+export function orderPolicyRules(rules) {
+    return [
+        ...rules.filter((r) => !isPatternRule(r.match)),
+        ...rules.filter((r) => isPatternRule(r.match)),
+    ];
+}
+/**
+ * The choice to render for one tool.
+ *
+ * `effective` is the server resolving every scope through the same function
+ * the call gate uses, so it is preferred whenever it covers the tool. It does
+ * not always: a connector that exists only in kortix.yaml with no materialized
+ * row comes back with `effective: []`
+ * (apps/api/src/connectors/db-deps.ts:1151), and older servers omit the field
+ * entirely. Falling back to the stored exact rule keeps the control live in
+ * both cases instead of showing every tool as unset.
+ */
+export function toolChoice(path, policies, effective) {
+    if (effective.some((e) => e.path === path))
+        return effectiveChoice(path, effective);
+    // Case-insensitive, like the engine — `GetPetById` governs `getpetbyid`.
+    const needle = path.toLowerCase();
+    const exact = policies.find((p) => !isPatternRule(p.match) && p.match.toLowerCase() === needle);
+    return exact ? exact.action : 'default';
+}
+/**
+ * What `effective` will look like once the server applies this change — used
+ * to keep an optimistic update honest.
+ *
+ * Without it the control would snap back to the old value between the click
+ * and the refetch, because the row reads `effective`, not `policies`. A
+ * project-scope entry is left alone: the server would not move it either, and
+ * those rows are disabled anyway.
+ *
+ * `'default'` DROPS the entry instead of guessing a replacement action. What
+ * the tool falls back to — a surviving glob, the risk default, `allow_all` —
+ * is the engine's decision, and inventing one here would put a value on screen
+ * the server never said. `toolChoice` reads `'default'` from the absence, so
+ * the control lands on Default immediately and the refetch fills in the truth.
+ */
+export function previewEffective(effective, paths, choice) {
+    const targets = new Set(paths);
+    const touched = (entry) => targets.has(entry.path) && entry.source !== 'project';
+    if (choice === 'default')
+        return effective.filter((entry) => !touched(entry));
+    return effective.map((entry) => touched(entry) ? { path: entry.path, action: choice, source: 'connector' } : entry);
+}

package/dist/customize/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @kortix/ui/customize — The project configuration pages (connectors, agents, triggers,
+ * secrets, models, skills, settings). Each takes `projectId`.
+ */
+export { AgentPage } from './agents/agent-page.js';
+export { AgentsPage } from './agents/agents-page.js';
+export { ConnectorsPage } from './connectors/connectors-page.js';
+export { ModelsPage } from './models/models-page.js';
+export { ProjectSettingsPage } from './project-settings/project-settings-page.js';
+export { SecretsPage } from './secrets/secrets-page.js';
+export { CapabilityPageShell } from './shared/capability-page-shell.js';
+export { SkillsPage } from './skills/skills-page.js';
+export { TriggersPage } from './triggers/triggers-page.js';

package/dist/customize/index.js

@@ -0,0 +1,13 @@
+/**
+ * @kortix/ui/customize — The project configuration pages (connectors, agents, triggers,
+ * secrets, models, skills, settings). Each takes `projectId`.
+ */
+export { AgentPage } from './agents/agent-page.js';
+export { AgentsPage } from './agents/agents-page.js';
+export { ConnectorsPage } from './connectors/connectors-page.js';
+export { ModelsPage } from './models/models-page.js';
+export { ProjectSettingsPage } from './project-settings/project-settings-page.js';
+export { SecretsPage } from './secrets/secrets-page.js';
+export { CapabilityPageShell } from './shared/capability-page-shell.js';
+export { SkillsPage } from './skills/skills-page.js';
+export { TriggersPage } from './triggers/triggers-page.js';

package/dist/customize/migrate-to-v2/index.d.ts

@@ -0,0 +1,6 @@
+export { detectManifestVersion, manifestFilename, manifestNeedsUpgrade, useProjectManifestVersion, type ManifestVersion, type ProjectManifestVersionState, } from '../../internal/lib/manifest-version.js';
+export { MIGRATE_TO_V2_PROMPT } from './migration-prompt.js';
+export { PROJECT_UPGRADES, applicableUpgrades, buildOneOffUpgradePrompt, type ProjectUpgrade, type ProjectUpgradeContext, } from './upgrade-defs.js';
+export { UpgradesView, UpgradesViewContent } from './upgrade-view.js';
+export { useMigrateToV2, type MigrateToV2 } from './use-migrate-to-v2.js';
+export { useRunUpgrade, type RunUpgrade } from './use-run-upgrade.js';

package/dist/customize/migrate-to-v2/index.js

@@ -0,0 +1,6 @@
+export { detectManifestVersion, manifestFilename, manifestNeedsUpgrade, useProjectManifestVersion, } from '../../internal/lib/manifest-version.js';
+export { MIGRATE_TO_V2_PROMPT } from './migration-prompt.js';
+export { PROJECT_UPGRADES, applicableUpgrades, buildOneOffUpgradePrompt, } from './upgrade-defs.js';
+export { UpgradesView, UpgradesViewContent } from './upgrade-view.js';
+export { useMigrateToV2 } from './use-migrate-to-v2.js';
+export { useRunUpgrade } from './use-run-upgrade.js';

package/dist/customize/migrate-to-v2/migration-prompt.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The seed prompt for "Migrate to v2" — a normal agent session does the
+ * conversion because it's just files + git (Marko's framing). We start a
+ * fresh session with this as the first message; the project's default agent
+ * reads the repo, rewrites the manifest, and opens a change request for a
+ * human to review. Nothing here merges anything — that's the whole point of
+ * routing config changes through the same CR path as any other edit.
+ *
+ * Simplified by the 2026-07-05 redirect ("one home per concern"): v1's `.md` frontmatter
+ * IS already valid v2 OpenCode behavior — a stock OpenCode agent file, no
+ * Kortix-specific split. The manifest side therefore touches ONLY governance
+ * (kortix.toml's `[[agents]]` → kortix.yaml's `agents:` map). The same change
+ * request also moves the project to the root layout (`agents/`, `skills/`,
+ * `memory/`, `harnesses/opencode/`; see `@kortix/manifest-schema/layout`):
+ * each agent's `.md` moves with `git mv`, and only its old path references
+ * change.
+ *
+ * The prompt carries the ENTIRE v1→v2 contract inline — every clean-break the
+ * v2 validator enforces, a worked before/after example, and pointers to the
+ * canonical JSON Schema (`kortix schema --version 2` in the sandbox, or the
+ * published kortix.com/schema documents) — so the agent never has to guess at
+ * the target shape and `kortix validate` passes on the first try.
+ *
+ * Kept as a plain exported constant (not inlined at the call site) so it's
+ * independently testable and diffable — this is the load-bearing artifact of
+ * the feature, not the wiring around it.
+ */
+export declare const MIGRATE_TO_V2_PROMPT = "Migrate this project's manifest from kortix_version 1 (kortix.toml) to kortix_version 2 (kortix.yaml), and move its files to the root layout. Read everything first, then make the change, then land it as a change request \u2014 do not merge it yourself.\n\n## 1. Read before you write\n\n- The current manifest: `kortix.toml` (or `kortix.yaml` if this project already partially moved \u2014 check `kortix_version` at the top either way).\n- Any `[[agents]]` entries in the v1 manifest \u2014 these carry `connectors`, `kortix_permissions` (older manifests spell it `kortix_cli`), and `env` grants per agent name. An agent name with NO `[[agents]]` entry at all is today unrestricted (v1's back-compat default is \"all\" when a grant key is omitted).\n- `.kortix/opencode/opencode.jsonc` \u2014 if it sets a top-level `default_agent`, that is the project's existing default; use it. If it doesn't, pick the agent whose `.kortix/opencode/agents/*.md` frontmatter has `mode: primary` and reads as the general/primary one (usually the first-created or the one with the broadest permissions). Record which you picked and why in the change request description \u2014 a human reviews this before it merges, so a defensible choice beats blocking on it.\n- **You do NOT need to read each agent's `.md` frontmatter to migrate it.** v1's frontmatter (mode/model/temperature/permission/prompt/\u2026) is ALREADY valid v2 OpenCode behavior \u2014 its content stays unchanged. Only the file moves (section 5). The manifest conversion is governance-only.\n- The current layout: v1 projects keep agents in `.kortix/opencode/agents/`, skills in `.kortix/opencode/skills/`, the other OpenCode files in `.kortix/opencode/`, and memory in `.kortix/memory/`. A v1 manifest that sets `opencode.config_dir` uses that directory instead of `.kortix/opencode`.\n\n## 2. Bring the platform baseline up to date first\n\nA project still on a v1 manifest is usually also running stale platform skills. Refresh them BEFORE touching the manifest so the migration lands on a current baseline:\n\n1. `kortix marketplace updates` \u2014 a hash-diff report of every marketplace-tracked item (the kortix-managed skills like `kortix-system`/`kortix-memory`, plus any marketplace skills the user installed).\n2. If updates are listed, apply them: `kortix marketplace update --all`. **This commits directly to `main` through the platform's own hash-safe update path \u2014 it is intentionally NOT part of your change request.** It only rewrites files whose installed hash no longer matches the catalog, so untouched user files are never clobbered.\n3. Sync your session branch on top of the refreshed main: `git fetch origin && git rebase origin/main`.\n4. Items reported as `orphaned` (no longer in the catalog) are not updatable \u2014 leave them alone and mention them in the change request description.\n5. Marketplace-tracked items are the ONLY thing you refresh this way. Do NOT hand-update anything else \"to latest\": agents' `.md` files, the memory directory, `opencode.jsonc`, the continuation plugin, `tools/*.ts`, and custom skills are user- or platform-owned files with no update tracking \u2014 leave every one of them untouched. Section 5 moves some of them and rewrites their old paths; that is the only change they get.\n\n## 3. The authoritative schema is one command away\n\nWhenever you are unsure about a field name, an allowed value, or whether a key survived into v2, consult the canonical JSON Schema instead of guessing:\n\n- `kortix schema --version 2` \u2014 prints the exact v2 schema the validator and the CR-merge gate enforce. Works offline inside your sandbox. `kortix schema --version 1` prints the v1 shape you are migrating FROM.\n- The same documents are published at `https://kortix.com/schema/kortix.v2.schema.json` (and `kortix.v1.schema.json`, plus the combined `kortix.schema.json` that dispatches on `kortix_version`).\n\nThe schema, this prompt, and `kortix validate` all enforce the same rules \u2014 if they ever appear to disagree, trust `kortix validate`'s output and say so in the change request description.\n\n## 4. The v2 shape you're producing\n\nv2's `agents:` map is GOVERNANCE ONLY \u2014 connectors/secrets/skills/kortix_permissions/workspace/enabled. OpenCode behavior (mode/model/temperature/permission/the prompt itself) is NOT part of the manifest at all; it lives entirely in each agent's own `.md` frontmatter + body, exactly as it does today. After section 5 that file is `agents/<name>.md`, and the agent's `file:` key names it.\n\n```yaml\nkortix_version: 2\ndefault_agent: <name>          # REQUIRED \u2014 must resolve to a declared, enabled agent below\n\nagents:\n  <name>:\n    file: agents/<name>.md       # the agent's .md, repo-relative (section 5 moves it there)\n    enabled: true                # optional; false = can't start sessions (default true)\n    connectors: all               # connector slugs | \"all\" | \"none\"\n    secrets: all                  # renamed from v1's \"env\" \u2014 names | \"all\" | \"none\"\n    kortix_permissions: all        # project.* permission names | \"all\" | \"none\"\n    skills: all                    # names of skills/* this agent may invoke | \"all\" | \"none\"\n    workspace:\n      project_repository: false    # optional \u2014 true (default) | false\n```\n\nThat's the WHOLE block. No `description`, no `model`, no `opencode:` sub-object, no `mode`/`temperature`/`permission`/`prompt` \u2014 every one of those is a hard schema error if authored here. They already live in the `.md` and are staying there.\n\nRules that the schema enforces (get these right or `kortix validate` fails):\n\n- `agents` is a MAP (`name: {...}`), not the v1 `[[agents]]` array of tables.\n- `default_agent` is required at the top level and must name a declared, enabled (`enabled` not `false`) agent.\n- Any behavioral field (`description`, `model`, `mode`, `temperature`, `top_p`, `steps`, `variant`, `color`, `hidden`, `permission`, `prompt`, or a nested `opencode:` block) authored on the manifest agent block is a hard error, pointing you at the agent's own `.md` frontmatter instead \u2014 because that's where it already lives, untouched.\n- `disable` is a hard error too \u2014 it's the manifest-governance `enabled` (inverted): write `enabled: false` instead. (This is unrelated to a NATIVE `disable` key that might already be hand-authored in an agent's own `.md` frontmatter \u2014 leave that alone; it's a different, runtime-level concept.)\n- `env` is a hard error in v2 \u2014 it is renamed `secrets`. **v2 defaults every omitted grant (`connectors`/`secrets`/`kortix_permissions`/`skills`) to `\"none\"` (deny-by-default), unlike v1 which defaulted an omitted grant to `\"all\"`.** To avoid silently narrowing an agent's access during migration, write the EXPLICIT value that reproduces today's behavior for every agent \u2014 if a v1 agent had no `[[agents]]` entry, or its `env`/`connectors`/`kortix_cli` (or `kortix_permissions`) were omitted or set to `all`, write `secrets: all`, `connectors: all`, `kortix_permissions: all` explicitly in its v2 block. Only narrow a grant if the v1 manifest already narrowed it (an explicit list, or `none`) \u2014 carry that exact list over. `skills` has no v1 equivalent; default new agents to `all` unless you have a specific reason to narrow.\n- `channels` is removed entirely in v2 \u2014 delete any `[[channels]]` block. Channel\u2194agent routing now lives in the dashboard (Customize \u2192 Channels), not in git. Do not try to replicate it in the manifest.\n- Every other top-level section (`project`, `env` for required/optional documentation vars \u2014 NOT the per-agent grant, `sandbox`, `triggers`, `connectors`, `apps`) keeps its v1 shape unchanged \u2014 translated to YAML, not restructured. `opencode.config_dir` is the one exception: section 5 sets it. If `triggers[].agent` names an agent, make sure that name still exists in the new `agents` map (rename references if you renamed an agent).\n- If an agent has no `.md` today (a bare `[[agents]]` entry with no matching OpenCode agent file), still declare it in `agents:` with its governance grants carried over \u2014 don't drop it. Omit its `file:` key. It has no behavior until someone adds `agents/<name>.md`.\n\n## 5. Move to the root layout\n\nv2 projects keep harness-neutral files at the repo root. Move this project in the same change request. Use `git mv`, so git records every move as a rename and keeps each file's history.\n\n| From | To |\n| --- | --- |\n| `.kortix/opencode/agents/<name>.md` | `agents/<name>.md` |\n| `.kortix/opencode/skills/<name>/` | `skills/<name>/` |\n| `.kortix/memory/` | `memory/` |\n| the rest of `.kortix/opencode/` (`opencode.jsonc`, `package.json`, `bun.lock`, `plugins/`, `tools/`, `commands/`) | `harnesses/opencode/` |\n\nIf the v1 manifest sets `opencode.config_dir`, that directory is the source instead of `.kortix/opencode`. Skip a row when its source does not exist.\n\n```\nmkdir -p harnesses\ngit mv .kortix/opencode/agents agents\ngit mv .kortix/opencode/skills skills\ngit mv .kortix/memory memory\ngit mv .kortix/opencode harnesses/opencode\n```\n\n`git mv <dir> <target>` moves `<dir>` INTO `<target>` when `<target>` already exists. Check each target with `ls` first. When it exists, move the entries one at a time (`git mv .kortix/opencode/skills/<name> skills/<name>`).\n\nThen:\n\n1. Set the OpenCode config dir in `kortix.yaml`: `opencode:` with `config_dir: harnesses/opencode`.\n2. Give every agent whose `.md` you moved a `file:` key: `file: agents/<name>.md`.\n3. Update `.gitignore`: rewrite each `.kortix/opencode/<path>` entry as `harnesses/opencode/<path>`, and each `.kortix/memory/<path>` entry as `memory/<path>`. Keep `.kortix/state/` \u2014 runtime state stays there.\n4. Find every remaining reference to an old path: `git grep -n -e '.kortix/opencode' -e '.kortix/memory'`. Replace each one with its new path. For example, `tools/memory.ts` hard-codes `.kortix/memory`, and agent prompts often name it. Change only the path. Leave `.kortix/state/` and `.kortix/link.json` references alone.\n\nEdge cases:\n\n- A root `agents/`, `memory/`, or `harnesses/` directory that already holds files unrelated to Kortix: do not merge into it. Skip this whole section, steps 1\u20134 included, keep the legacy layout (Kortix still reads it), and say why in the change request description.\n- A skill that already exists in `skills/<name>/` (the marketplace update in section 2 can install it there): keep the root copy and remove the legacy copy with `git rm -r`.\n\n## 6. Legacy keys v2 refuses \u2014 drop these while you convert\n\nv1 tolerates several retired keys with a deprecation warning; v2 makes every one of them a hard error. Remove them as part of the conversion and note each removal in the change request description:\n\n- **Retired `kortix_permissions` actions** \u2014 `project.session.exec`, `project.gateway.routing.edit`, `project.schedule.read`, `project.schedule.write`, `project.webhook.read`, `project.webhook.write`, `channel.read`, `channel.connect`, `channel.send`, `channel.disconnect`. These were removed from the enforcement catalog and have been no-ops for a while \u2014 granting or omitting them never had any effect, so deleting them from a grant list changes nothing. Do NOT substitute a broader grant (e.g. `all`) to \"cover\" a deleted action.\n- **`credential = \"per_user\"` on a `[[connectors]]` entry** \u2014 the per-user credential mode was removed; every connector is `\"shared\"` now. Delete the `credential` key (or write `shared` explicitly if the entry already spelled it out).\n- **`agent_scope` on a `[[connectors]]` entry** \u2014 retired; the runtime no longer reads it. Per-agent connector access is expressed from the OTHER side now: each agent's `connectors:` grant in the `agents:` map. If a v1 connector had `agent_scope = [\"a\", \"b\"]`, make sure agents outside that list don't get that connector slug in their `connectors` grant (use an explicit slug list instead of `all` for the agents that should keep access), then delete the key.\n- **Legacy singular `[sandbox]` image keys** (`image`, `dockerfile`, `cpu`, `memory`, `disk`, \u2026) \u2014 already an error in v1's validator; if `kortix validate` flags them, move the image definition under `[[sandbox.templates]]` \u2192 `sandbox.templates:` with a named slug.\n\n## 7. Worked example\n\nA representative v1 `kortix.toml`:\n\n```toml\nkortix_version = 1\n\n[project]\nname = \"acme-ops\"\n\n[env]\nrequired = [\"DATABASE_URL\"]\n\n[[agents]]\nname = \"dev\"\nconnectors = [\"github\", \"linear\"]\nenv = \"all\"\nkortix_cli = [\"project.file.read\", \"project.file.write\", \"project.session.exec\"]\n\n[[agents]]\nname = \"support\"\n# no grants declared \u2014 v1 treats omitted grants as \"all\"\n\n[[channels]]\ntype = \"slack\"\nagent = \"support\"\n\n[[triggers]]\nslug = \"weekly-summary\"\ntype = \"cron\"\ncron = \"0 9 * * 1\"\nagent = \"dev\"\nprompt = \"Post the weekly summary.\"\n\n[[connectors]]\nslug = \"github\"\nprovider = \"github\"\ncredential = \"per_user\"\nagent_scope = [\"dev\"]\n```\n\nbecomes this v2 `kortix.yaml`:\n\n```yaml\nkortix_version: 2\ndefault_agent: dev\n\nproject:\n  name: acme-ops\n\nenv:\n  required:\n    - DATABASE_URL\n\nopencode:\n  config_dir: harnesses/opencode\n\nagents:\n  dev:\n    file: agents/dev.md\n    connectors:\n      - github\n      - linear\n    secrets: all          # v1 \"env = all\", renamed\n    kortix_permissions:   # renamed from v1's kortix_cli; project.session.exec dropped \u2014 retired no-op action\n      - project.file.read\n      - project.file.write\n    skills: all\n  support:\n    file: agents/support.md\n    # v1 had no grants (implicit all) \u2014 but the github connector was\n    # agent_scoped to dev only, so \"all\" would WIDEN support's access.\n    # An explicit list preserves today's effective behavior instead.\n    connectors: none\n    secrets: all\n    kortix_permissions: all\n    skills: all\n\ntriggers:\n  - slug: weekly-summary\n    type: cron\n    cron: \"0 9 * * 1\"\n    agent: dev\n    prompt: Post the weekly summary.\n\nconnectors:\n  - slug: github\n    provider: github\n    # credential/agent_scope removed \u2014 connectors are shared; per-agent\n    # access now lives in the agents map above.\n```\n\nNote what happened: the `[[channels]]` block is gone (dashboard-owned now), each agent names its moved `.md` with `file:`, `opencode.config_dir` points at `harnesses/opencode`, `env` became `secrets`, the retired CLI action and connector keys were dropped, every omitted-in-v1 grant was written out explicitly, and the old `agent_scope` was honored by adjusting the AGENTS' `connectors` grants rather than copied over. Your project will differ \u2014 apply the rules, not this output verbatim.\n\n## 8. Leave every agent's `.md` alone\n\nBeyond the move and the path updates in section 5, do not edit or reformat any agent's `.md` as part of this migration. Its frontmatter (mode/model/permission/temperature/\u2026) and body (the system prompt) are ALREADY the agent's v2 behavior \u2014 nothing else about them needs to change. This is what keeps the manifest conversion governance-only and comparatively small: you're translating one array-of-tables into one map of governance grants, full stop.\n\n## 9. Write the file, remove the old one\n\n- Write the fully assembled manifest to `kortix.yaml` at the repo root (same directory as the old `kortix.toml`).\n- If the project has more than ~10 triggers, or long multi-line prompts, keep `kortix.yaml` readable: add `imports: [triggers/]` to the root and write the triggers into YAML files under `triggers/` (one file per trigger or per group; each file is a `triggers:` list). Every other key stays in `kortix.yaml`. Slugs must stay unique across all files.\n- Carry over meaningful TOML comments as YAML comments next to the same keys \u2014 hand-written context in a manifest is documentation someone chose to leave; don't strip it.\n- Delete the old `kortix.toml` in the same commit \u2014 don't leave both files (the platform always prefers `kortix.yaml` when both exist, but a stale v1 file next to it is confusing for the next person who edits by hand).\n- You do not need to touch any project setting outside git \u2014 the platform resolves `kortix.yaml` automatically once it exists, regardless of the configured manifest filename.\n\n## 10. Validate before you're done\n\nRun `kortix validate` (it auto-detects `kortix.yaml`). Fix every error it reports \u2014 do not open the change request with a manifest that fails validation. Warnings are fine to leave if they're informational, but read them. If an error surprises you, cross-check the field against `kortix schema --version 2`.\n\n## 11. Land it as a change request \u2014 never merge\n\nFirst, re-sync: `git fetch origin` and check whether `origin/main` advanced while you worked (`git log HEAD..origin/main --oneline`) \u2014 on active projects it will (connectors added from the dashboard, other sessions merging). If it moved, rebase; if the rebase conflicts on `kortix.toml` (main changed the manifest you deleted), don't fight it \u2014 `git rebase --abort`, `git reset --hard origin/main`, and redo the conversion against the CURRENT manifest, then continue. Never revert main's changes to win a conflict.\n\nThen commit, **push the branch**, and open the change request. A commit that is never pushed leaves the CR empty (\"No changes detected\") and un-appliable \u2014 the platform refuses such a CR outright (`422 CR_HEAD_NOT_AHEAD`):\n\n```\ngit add -A && git commit -m \"Migrate to kortix_version 2 (kortix.yaml) and the root layout\"\ngit push origin HEAD\nkortix cr open --head <your-branch> --title \"Migrate to kortix_version 2 (kortix.yaml) and the root layout\" --description \"<what you converted, which files you moved, which agent you picked as default_agent and why, every legacy key you removed, and any grant you had to leave narrowed>\"\n```\n\nIf the push is rejected because the remote session branch moved, `git fetch origin` then `git push --force-with-lease origin HEAD` \u2014 your own session branch only, never any other branch.\n\nThen verify the CR actually carries your diff: run `kortix cr diff <number>` \u2014 if it reports no changes, your push didn't land; push again and re-check (the CR updates automatically, do not open a second one).\n\nDo **not** run `kortix cr merge`. This is a human-reviewed change like any other \u2014 stop once the CR is open and verified non-empty, and tell the user its number so they can review the diff and merge it themselves.";