@kortix/ui 0.14.8 → 0.14.10

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

@@ -1,13 +1,35 @@
+/** The `effective.source` that marks a decision made in the list being edited. */
+function ownSource(scope) {
+    return scope === 'set' ? 'policy_set' : 'connector';
+}
 /**
  * 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) {
+export function effectiveChoice(path, effective, scope = 'base') {
     const hit = effective.find((e) => e.path === path);
     if (!hit)
         return 'default';
-    return hit.source === 'connector' || hit.source === 'project' ? hit.action : 'default';
+    return hit.source === ownSource(scope) || hit.source === 'project' ? hit.action : 'default';
+}
+/**
+ * What the Default segment (base rules) or the Inherit segment (a set)
+ * resolves to for one tool, so the control can say it: "Default · runs",
+ * "Inherit · blocked".
+ *
+ * - In a set, the base rules decide an inherited tool: `baseEffective` is the
+ *   server's answer for the base list.
+ * - While the tool is on Default/Inherit, its own `effective` entry is that
+ *   answer too (a pattern rule, the risk default, `allow_all`).
+ * - Otherwise the connector default (`fallback`) decides.
+ */
+export function inheritedAction(path, choice, effective, baseEffective, scope, fallback) {
+    const base = scope === 'set' ? baseEffective.find((e) => e.path === path) : undefined;
+    if (base)
+        return base.action;
+    const own = choice === 'default' ? effective.find((e) => e.path === path) : undefined;
+    return own?.action ?? fallback;
 }
 /**
  * Project-scope rules are evaluated first and win
@@ -41,7 +63,9 @@ 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()));
+    // A conditional rule (`conditions:` in kortix.yaml) is kept too: a per-tool
+    // click has no way to express it, and replacing it would drop the condition.
+    const kept = rules.filter((r) => isAdvancedRule(r) || !targets.has(r.match.toLowerCase()));
     if (choice === 'default')
         return kept;
     return [...kept, ...paths.map((match) => ({ match, action: choice }))];
@@ -56,6 +80,13 @@ export function applyBulkPolicy(rules, paths, choice) {
 export function isPatternRule(match) {
     return match.includes('*') || /^\/.*\/[a-z]*$/.test(match);
 }
+/**
+ * A rule the per-tool control cannot represent: a pattern, or a rule with
+ * argument conditions. Both live in the Advanced editor.
+ */
+export function isAdvancedRule(rule) {
+    return isPatternRule(rule.match) || (rule.conditions?.length ?? 0) > 0;
+}
 /**
  * Order a rule set for the wire.
  *
@@ -84,12 +115,12 @@ export function orderPolicyRules(rules) {
  * 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) {
+export function toolChoice(path, policies, effective, scope = 'base') {
     if (effective.some((e) => e.path === path))
-        return effectiveChoice(path, effective);
+        return effectiveChoice(path, effective, scope);
     // Case-insensitive, like the engine — `GetPetById` governs `getpetbyid`.
     const needle = path.toLowerCase();
-    const exact = policies.find((p) => !isPatternRule(p.match) && p.match.toLowerCase() === needle);
+    const exact = policies.find((p) => !isAdvancedRule(p) && p.match.toLowerCase() === needle);
     return exact ? exact.action : 'default';
 }
 /**
@@ -107,10 +138,45 @@ export function toolChoice(path, policies, effective) {
  * 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) {
+export function previewEffective(effective, paths, choice, scope = 'base') {
     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);
+    return effective.map((entry) => touched(entry) ? { path: entry.path, action: choice, source: ownSource(scope) } : entry);
+}
+/**
+ * What a tool does when no rule names it: the server's default
+ * (`resolveEffectiveAction`, connectors/policy.ts). A sensitive connector asks
+ * for every tool, `allow_all` runs every tool, and otherwise reads run and
+ * writes ask.
+ */
+export function connectorDefaultAction(sensitive, defaultMode, risk) {
+    if (sensitive)
+        return 'require_approval';
+    if (defaultMode === 'allow_all')
+        return 'always_run';
+    return risk === 'read' ? 'always_run' : 'require_approval';
+}
+/**
+ * The counts above the tool list: what each tool does on its next call, and
+ * how many tools this list changes. `effective` is the server's answer and
+ * wins; `fallback` names what a tool with no entry does.
+ */
+export function summarizeToolDecisions(actions, policies, effective, scope, fallback) {
+    const summary = { total: actions.length, block: 0, ask: 0, run: 0, changed: 0 };
+    for (const action of actions) {
+        const choice = toolChoice(action.path, policies, effective, scope);
+        const decided = effective.find((entry) => entry.path === action.path)?.action ??
+            (choice === 'default' ? fallback(action) : choice);
+        if (decided === 'block')
+            summary.block++;
+        else if (decided === 'require_approval')
+            summary.ask++;
+        else
+            summary.run++;
+        if (choice !== 'default' && !isLockedByProject(action.path, effective))
+            summary.changed++;
+    }
+    return summary;
 }

package/dist/customize/connectors/use-agent-access.d.ts

@@ -0,0 +1,85 @@
+import { type AgentGrants } from './agent-access.js';
+/**
+ * The project's agents and their connector grants and rule sets, plus the two
+ * writes: give or take a connector, and pick an agent's rule set on it. Both
+ * commit kortix.yaml through `PUT …/agents/{name}/scope`.
+ *
+ * `supported` is false on a v1 manifest: its agents are a TOML overlay this
+ * reader does not parse, and rule sets need v2.
+ */
+export declare function useAgentAccess(projectId: string): {
+    isPending: boolean;
+    isError: boolean;
+    error: Error | null;
+    refetch: (options?: import("@tanstack/react-query").RefetchOptions) => Promise<import("@tanstack/react-query").QueryObserverResult<{
+        config: {
+            default_agent: string | null;
+            is_kortix_repo: boolean;
+            signals: Record<string, boolean>;
+            manifest_raw: string | null;
+            open_code_raw: string | null;
+            open_code_default_agent: string | null;
+            agent_discovery: "opencode" | "declarative";
+            agents: Array<{
+                name: string;
+                path: string;
+                description: string | null;
+                mode: string | null;
+                hidden?: boolean;
+                model?: string | null;
+                source?: "opencode" | "kortix.toml";
+                enabled?: boolean;
+                platform?: boolean;
+                sandbox?: string | null;
+                scope?: {
+                    env: string[] | "all";
+                    connectors: string[] | "all";
+                    kortix_permissions?: string[] | "all";
+                    kortix_cli: string[] | "all";
+                    apps?: string[] | "all";
+                };
+            }>;
+            skills: Array<{
+                name: string;
+                path: string;
+                description: string | null;
+            }>;
+            commands: Array<{
+                name: string;
+                path: string;
+                description: string | null;
+            }>;
+            env: {
+                required: string[];
+                optional: string[];
+            };
+        };
+        project: import("@kortix/sdk").KortixProject;
+        git_connection?: import("@kortix/sdk").ProjectGitConnection | null;
+        file_count: number;
+        files: import("@kortix/sdk").ProjectFileEntry[];
+    }, Error>>;
+    supported: boolean;
+    canEdit: boolean;
+    agents: string[];
+    grantsOf: (agent: string) => AgentGrants | undefined;
+    pending: string | null;
+    /** Give (`on`) or take one connector. `allSlugs` are the project's connectors. */
+    setGrant: (agent: string, slug: string, on: boolean, allSlugs: readonly string[]) => Promise<{
+        ok: boolean;
+        agent: string;
+        env: import("@kortix/sdk").AgentGrantSet;
+        connectors: import("@kortix/sdk").AgentGrantSet;
+        connectors_required: string[];
+        policy_sets?: Record<string, string>;
+    }>;
+    /** Pick the agent's rule set on a connector; null is the base rules. Grants the connector too. */
+    setPolicySet: (agent: string, slug: string, set: string | null, allSlugs: readonly string[]) => Promise<{
+        ok: boolean;
+        agent: string;
+        env: import("@kortix/sdk").AgentGrantSet;
+        connectors: import("@kortix/sdk").AgentGrantSet;
+        connectors_required: string[];
+        policy_sets?: Record<string, string>;
+    }>;
+};

package/dist/customize/connectors/use-agent-access.js

@@ -0,0 +1,72 @@
+'use client';
+import { getProjectDetail, setAgentScope } from '@kortix/sdk';
+import { contract, qk, useProjectAccountId } from '@kortix/sdk/react';
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import { useMemo } from 'react';
+import { errorToast } from '../../primitives/toast.js';
+import { PROJECT_ACTIONS } from '../../internal/lib/project-actions.js';
+import { useProjectCans } from '../../internal/lib/use-project-can.js';
+import { manifestAgentGrants, withConnectorGrant } from './agent-access.js';
+const ACTIONS = [PROJECT_ACTIONS.PROJECT_AGENT_WRITE, PROJECT_ACTIONS.PROJECT_CONNECTOR_WRITE];
+/**
+ * The project's agents and their connector grants and rule sets, plus the two
+ * writes: give or take a connector, and pick an agent's rule set on it. Both
+ * commit kortix.yaml through `PUT …/agents/{name}/scope`.
+ *
+ * `supported` is false on a v1 manifest: its agents are a TOML overlay this
+ * reader does not parse, and rule sets need v2.
+ */
+export function useAgentAccess(projectId) {
+    const queryClient = useQueryClient();
+    const accountId = useProjectAccountId(projectId);
+    const cans = useProjectCans(projectId, ACTIONS, { accountId });
+    const canEdit = cans[PROJECT_ACTIONS.PROJECT_AGENT_WRITE]?.allowed === true &&
+        cans[PROJECT_ACTIONS.PROJECT_CONNECTOR_WRITE]?.allowed === true;
+    const projectQuery = useQuery({
+        queryKey: qk.project.detail(projectId),
+        queryFn: () => getProjectDetail(projectId),
+        ...contract('config'),
+    });
+    const config = projectQuery.data?.config;
+    const grants = useMemo(() => manifestAgentGrants(config?.manifest_raw), [config?.manifest_raw]);
+    const agents = useMemo(() => {
+        const names = new Set(Object.keys(grants ?? {}));
+        for (const agent of config?.agents ?? [])
+            if (!agent.hidden)
+                names.add(agent.name);
+        return [...names].sort((a, b) => a.localeCompare(b));
+    }, [grants, config?.agents]);
+    const write = useMutation({
+        mutationFn: (input) => setAgentScope(projectId, input.agent, input.scope),
+        onError: (error) => errorToast(error.message),
+        onSettled: () => {
+            void queryClient.invalidateQueries({ queryKey: qk.project.detail(projectId) });
+            void queryClient.invalidateQueries({ queryKey: ['connector-policy-sets', projectId] });
+        },
+    });
+    const grantsOf = (agent) => grants?.[agent];
+    return {
+        isPending: projectQuery.isPending,
+        isError: projectQuery.isError,
+        error: projectQuery.error,
+        refetch: projectQuery.refetch,
+        supported: grants !== null,
+        canEdit,
+        agents,
+        grantsOf,
+        pending: write.isPending ? write.variables?.agent ?? null : null,
+        /** Give (`on`) or take one connector. `allSlugs` are the project's connectors. */
+        setGrant: (agent, slug, on, allSlugs) => write.mutateAsync({
+            agent,
+            scope: { connectors: withConnectorGrant(grantsOf(agent), slug, on, allSlugs) },
+        }),
+        /** Pick the agent's rule set on a connector; null is the base rules. Grants the connector too. */
+        setPolicySet: (agent, slug, set, allSlugs) => write.mutateAsync({
+            agent,
+            scope: {
+                ...(set ? { connectors: withConnectorGrant(grantsOf(agent), slug, true, allSlugs) } : {}),
+                policy_sets: { [slug]: set },
+            },
+        }),
+    };
+}

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

@@ -1,6 +1,5 @@
 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 { MIGRATE_TO_V3_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

@@ -1,6 +1,5 @@
 export { detectManifestVersion, manifestFilename, manifestNeedsUpgrade, useProjectManifestVersion, } from '../../internal/lib/manifest-version.js';
-export { MIGRATE_TO_V2_PROMPT } from './migration-prompt.js';
+export { MIGRATE_TO_V3_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

@@ -1,29 +1,16 @@
 /**
- * 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.
+ * The seed prompt for "Upgrade manifest to v3": a normal agent session does
+ * the conversion, because it is files and git. Upgrading starts a fresh
+ * session with this as the first message; the project's default agent runs
+ * `kortix migrate`, checks what it cannot know, and opens a change request for
+ * a human to review. Nothing here merges anything.
  *
- * 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.
+ * `kortix migrate` (apps/cli/src/commands/migrate.ts) holds the conversion
+ * rules for kortix_version 1 and 2, so this prompt carries only what the tool
+ * cannot decide: the marketplace baseline, the checks after the conversion, the
+ * old folders, validation and the landing contract.
  *
- * 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.
- * @deprecated Moves a v1 project to the OpenCode-era v2 layout (harnesses/opencode). OpenCode is sunset (2026-10-23); migrate with `kortix migrate` to kortix_version 3.
+ * `kortix projects upgrade` (apps/cli/src/commands/projects.ts) sends a
+ * verbatim copy. `projects-parity.test.ts` fails when the two differ.
  */
-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.";
+export declare const MIGRATE_TO_V3_PROMPT = "Upgrade this project's manifest to kortix_version 3 (kortix.yaml). Check `kortix_version` at the top of the manifest first: kortix_version 1 is `kortix.toml`, 2 and 3 are `kortix.yaml`. On kortix_version 3 there is nothing to upgrade: say so and stop. Land the upgrade as a change request \u2014 do not merge it yourself.\n\n## 1. Bring the platform baseline up to date first\n\n1. `kortix marketplace updates` \u2014 a hash-diff report of every marketplace-tracked item (the Kortix-managed skills, 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.**\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.\n\n## 2. Convert with kortix migrate\n\n1. Run `kortix migrate`. It prints the plan, the new `kortix.yaml`, a \"Not carried over\" list, and whether the result validates. It changes nothing.\n2. Run `kortix migrate --write`. It writes the v3 `kortix.yaml`, moves each agent's behavior out of its `.md` frontmatter into its `agents.<name>` block, keeps the prompt in the `.md` as its `prompt_file`, and deletes `kortix.toml` and `opencode.json(c)`. It refuses a result that does not validate: fix what it reports, then run it again.\n3. Carry over by hand each \"Not carried over\" item that has a v3 key. `kortix schema --version 3` prints the exact schema. List each item that has no v3 key in the change request description; do not invent a key for it.\n\n## 3. Check what kortix migrate cannot decide\n\n- **Grants.** v3 grants are deny-by-default. Every agent must keep the access it has today: `skills`, `subagents`, `commands`, `extensions`, `connectors`, `secrets`, `kortix_permissions` and `workspace: { project_repository: true }` for an agent that works in the repository. Never widen a grant to cover a key you removed.\n- **The default agent.** `default_agent` must name a declared agent with `mode: primary` or `all`. A kortix_version 1 project takes it from `opencode.jsonc`, else from its first agent. Confirm the choice and record it and the reason in the change request description.\n- **Old folders.** v3 reads no harness folder: `harnesses/` and `.kortix/opencode/` are not read. Move every file that a registry or a `prompt_file` still names there to the root folders (`agents/`, `skills/`, `tools/`, `commands/`, `extensions/`) with `git mv`, and update the path in `kortix.yaml`. From kortix_version 1, also run `git mv .kortix/memory memory`. Keep `.kortix/state/` and `.kortix/link.json`. Then delete what is left: `git rm -r harnesses/` or `git rm -r .kortix/opencode/`.\n- **OpenCode-only extensions.** Every new session runs pi, and pi loads only an extension's `pi:` implementation. `kortix migrate` turns each OpenCode plugin into an extension with only an `opencode:` implementation (under `extensions/opencode/`), which never loads. Remove each such extension from `extensions` and from every agent's `extensions` grant, and `git rm -r` its files. List each one in the change request description; when it did something the project needs, say that a pi extension (`pi:`) replaces it.\n- **Old paths.** Run `git grep -n -e '.kortix/opencode' -e '.kortix/memory' -e 'harnesses/'` and replace each old path with the new one, in prompts, skills, tools and `.gitignore`. Change only the path.\n\n## 4. Validate before you are done\n\nRun `kortix validate`. Fix every error it reports. Do not open the change request with a manifest that fails validation.\n\n## 5. 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`). If it moved, rebase. If the rebase conflicts on the manifest or a moved file, `git rebase --abort`, `git reset --hard origin/main`, and redo the conversion against the current files. 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 (`422 CR_HEAD_NOT_AHEAD`):\n\n```\ngit add -A && git commit -m \"Upgrade to kortix_version 3\"\ngit push origin HEAD\nkortix cr open --head <your-branch> --title \"Upgrade to kortix_version 3\" --description \"<the default agent and why, every file you moved or removed, each agent's grants, every item kortix migrate did not carry over and why>\"\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 run `kortix cr diff <number>`. If it reports no changes, your push did not land; push again and re-check (the CR updates automatically, do not open a second one).\n\nDo **not** run `kortix cr merge`. 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.";