@kortix/ui 0.14.8 → 0.14.10

package/dist/customize/migrate-to-v2/migration-prompt.js

@@ -1,261 +1,59 @@
 /**
- * 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 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 — do not merge it yourself.
-
-## 1. Read before you write
-
-- The current manifest: \`kortix.toml\` (or \`kortix.yaml\` if this project already partially moved — check \`kortix_version\` at the top either way).
-- Any \`[[agents]]\` entries in the v1 manifest — 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).
-- \`.kortix/opencode/opencode.jsonc\` — 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 — a human reviews this before it merges, so a defensible choice beats blocking on it.
-- **You do NOT need to read each agent's \`.md\` frontmatter to migrate it.** v1's frontmatter (mode/model/temperature/permission/prompt/…) is ALREADY valid v2 OpenCode behavior — its content stays unchanged. Only the file moves (section 5). The manifest conversion is governance-only.
-- 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\`.
-
-## 2. Bring the platform baseline up to date first
+export 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 — do not merge it yourself.
 
-A 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:
+## 1. Bring the platform baseline up to date first
 
-1. \`kortix marketplace updates\` — 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).
-2. If updates are listed, apply them: \`kortix marketplace update --all\`. **This commits directly to \`main\` through the platform's own hash-safe update path — 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.
+1. \`kortix marketplace updates\` — a hash-diff report of every marketplace-tracked item (the Kortix-managed skills, plus any marketplace skills the user installed).
+2. If updates are listed, apply them: \`kortix marketplace update --all\`. **This commits directly to \`main\` through the platform's own hash-safe update path — it is intentionally NOT part of your change request.**
 3. Sync your session branch on top of the refreshed main: \`git fetch origin && git rebase origin/main\`.
 4. Items reported as \`orphaned\` (no longer in the catalog) are not updatable — leave them alone and mention them in the change request description.
-5. 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 — leave every one of them untouched. Section 5 moves some of them and rewrites their old paths; that is the only change they get.
-
-## 3. The authoritative schema is one command away
-
-Whenever 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:
-
-- \`kortix schema --version 2\` — 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.
-- 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\`).
-
-The schema, this prompt, and \`kortix validate\` all enforce the same rules — if they ever appear to disagree, trust \`kortix validate\`'s output and say so in the change request description.
-
-## 4. The v2 shape you're producing
-
-v2's \`agents:\` map is GOVERNANCE ONLY — 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.
-
-\`\`\`yaml
-kortix_version: 2
-default_agent: <name>          # REQUIRED — must resolve to a declared, enabled agent below
-
-agents:
-  <name>:
-    file: agents/<name>.md       # the agent's .md, repo-relative (section 5 moves it there)
-    enabled: true                # optional; false = can't start sessions (default true)
-    connectors: all               # connector slugs | "all" | "none"
-    secrets: all                  # renamed from v1's "env" — names | "all" | "none"
-    kortix_permissions: all        # project.* permission names | "all" | "none"
-    skills: all                    # names of skills/* this agent may invoke | "all" | "none"
-    workspace:
-      project_repository: false    # optional — true (default) | false
-\`\`\`
-
-That's the WHOLE block. No \`description\`, no \`model\`, no \`opencode:\` sub-object, no \`mode\`/\`temperature\`/\`permission\`/\`prompt\` — every one of those is a hard schema error if authored here. They already live in the \`.md\` and are staying there.
-
-Rules that the schema enforces (get these right or \`kortix validate\` fails):
-
-- \`agents\` is a MAP (\`name: {...}\`), not the v1 \`[[agents]]\` array of tables.
-- \`default_agent\` is required at the top level and must name a declared, enabled (\`enabled\` not \`false\`) agent.
-- 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 — because that's where it already lives, untouched.
-- \`disable\` is a hard error too — 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 — leave that alone; it's a different, runtime-level concept.)
-- \`env\` is a hard error in v2 — 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 — 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\`) — carry that exact list over. \`skills\` has no v1 equivalent; default new agents to \`all\` unless you have a specific reason to narrow.
-- \`channels\` is removed entirely in v2 — delete any \`[[channels]]\` block. Channel↔agent routing now lives in the dashboard (Customize → Channels), not in git. Do not try to replicate it in the manifest.
-- Every other top-level section (\`project\`, \`env\` for required/optional documentation vars — NOT the per-agent grant, \`sandbox\`, \`triggers\`, \`connectors\`, \`apps\`) keeps its v1 shape unchanged — 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).
-- 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 — don't drop it. Omit its \`file:\` key. It has no behavior until someone adds \`agents/<name>.md\`.
-
-## 5. Move to the root layout
-
-v2 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.
-
-| From | To |
-| --- | --- |
-| \`.kortix/opencode/agents/<name>.md\` | \`agents/<name>.md\` |
-| \`.kortix/opencode/skills/<name>/\` | \`skills/<name>/\` |
-| \`.kortix/memory/\` | \`memory/\` |
-| the rest of \`.kortix/opencode/\` (\`opencode.jsonc\`, \`package.json\`, \`bun.lock\`, \`plugins/\`, \`tools/\`, \`commands/\`) | \`harnesses/opencode/\` |
-
-If 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.
-
-\`\`\`
-mkdir -p harnesses
-git mv .kortix/opencode/agents agents
-git mv .kortix/opencode/skills skills
-git mv .kortix/memory memory
-git mv .kortix/opencode harnesses/opencode
-\`\`\`
-
-\`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>\`).
-
-Then:
-
-1. Set the OpenCode config dir in \`kortix.yaml\`: \`opencode:\` with \`config_dir: harnesses/opencode\`.
-2. Give every agent whose \`.md\` you moved a \`file:\` key: \`file: agents/<name>.md\`.
-3. Update \`.gitignore\`: rewrite each \`.kortix/opencode/<path>\` entry as \`harnesses/opencode/<path>\`, and each \`.kortix/memory/<path>\` entry as \`memory/<path>\`. Keep \`.kortix/state/\` — runtime state stays there.
-4. 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.
-
-Edge cases:
-
-- 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–4 included, keep the legacy layout (Kortix still reads it), and say why in the change request description.
-- 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\`.
-
-## 6. Legacy keys v2 refuses — drop these while you convert
-
-v1 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:
-
-- **Retired \`kortix_permissions\` actions** — \`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 — 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.
-- **\`credential = "per_user"\` on a \`[[connectors]]\` entry** — 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).
-- **\`agent_scope\` on a \`[[connectors]]\` entry** — 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.
-- **Legacy singular \`[sandbox]\` image keys** (\`image\`, \`dockerfile\`, \`cpu\`, \`memory\`, \`disk\`, …) — already an error in v1's validator; if \`kortix validate\` flags them, move the image definition under \`[[sandbox.templates]]\` → \`sandbox.templates:\` with a named slug.
-
-## 7. Worked example
-
-A representative v1 \`kortix.toml\`:
-
-\`\`\`toml
-kortix_version = 1
-
-[project]
-name = "acme-ops"
-
-[env]
-required = ["DATABASE_URL"]
-
-[[agents]]
-name = "dev"
-connectors = ["github", "linear"]
-env = "all"
-kortix_cli = ["project.file.read", "project.file.write", "project.session.exec"]
-
-[[agents]]
-name = "support"
-# no grants declared — v1 treats omitted grants as "all"
-
-[[channels]]
-type = "slack"
-agent = "support"
-
-[[triggers]]
-slug = "weekly-summary"
-type = "cron"
-cron = "0 9 * * 1"
-agent = "dev"
-prompt = "Post the weekly summary."
-
-[[connectors]]
-slug = "github"
-provider = "github"
-credential = "per_user"
-agent_scope = ["dev"]
-\`\`\`
-
-becomes this v2 \`kortix.yaml\`:
-
-\`\`\`yaml
-kortix_version: 2
-default_agent: dev
-
-project:
-  name: acme-ops
-
-env:
-  required:
-    - DATABASE_URL
-
-opencode:
-  config_dir: harnesses/opencode
-
-agents:
-  dev:
-    file: agents/dev.md
-    connectors:
-      - github
-      - linear
-    secrets: all          # v1 "env = all", renamed
-    kortix_permissions:   # renamed from v1's kortix_cli; project.session.exec dropped — retired no-op action
-      - project.file.read
-      - project.file.write
-    skills: all
-  support:
-    file: agents/support.md
-    # v1 had no grants (implicit all) — but the github connector was
-    # agent_scoped to dev only, so "all" would WIDEN support's access.
-    # An explicit list preserves today's effective behavior instead.
-    connectors: none
-    secrets: all
-    kortix_permissions: all
-    skills: all
-
-triggers:
-  - slug: weekly-summary
-    type: cron
-    cron: "0 9 * * 1"
-    agent: dev
-    prompt: Post the weekly summary.
-
-connectors:
-  - slug: github
-    provider: github
-    # credential/agent_scope removed — connectors are shared; per-agent
-    # access now lives in the agents map above.
-\`\`\`
-
-Note 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 — apply the rules, not this output verbatim.
 
-## 8. Leave every agent's \`.md\` alone
+## 2. Convert with kortix migrate
 
-Beyond 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/…) and body (the system prompt) are ALREADY the agent's v2 behavior — 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.
+1. Run \`kortix migrate\`. It prints the plan, the new \`kortix.yaml\`, a "Not carried over" list, and whether the result validates. It changes nothing.
+2. 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.
+3. 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.
 
-## 9. Write the file, remove the old one
+## 3. Check what kortix migrate cannot decide
 
-- Write the fully assembled manifest to \`kortix.yaml\` at the repo root (same directory as the old \`kortix.toml\`).
-- 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.
-- Carry over meaningful TOML comments as YAML comments next to the same keys — hand-written context in a manifest is documentation someone chose to leave; don't strip it.
-- Delete the old \`kortix.toml\` in the same commit — 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).
-- You do not need to touch any project setting outside git — the platform resolves \`kortix.yaml\` automatically once it exists, regardless of the configured manifest filename.
+- **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.
+- **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.
+- **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/\`.
+- **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.
+- **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.
 
-## 10. Validate before you're done
+## 4. Validate before you are done
 
-Run \`kortix validate\` (it auto-detects \`kortix.yaml\`). Fix every error it reports — 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\`.
+Run \`kortix validate\`. Fix every error it reports. Do not open the change request with a manifest that fails validation.
 
-## 11. Land it as a change request — never merge
+## 5. Land it as a change request — never merge
 
-First, re-sync: \`git fetch origin\` and check whether \`origin/main\` advanced while you worked (\`git log HEAD..origin/main --oneline\`) — 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 — \`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.
+First, 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.
 
-Then 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 — the platform refuses such a CR outright (\`422 CR_HEAD_NOT_AHEAD\`):
+Then commit, **push the branch**, and open the change request. A commit that is never pushed leaves the CR empty (\`422 CR_HEAD_NOT_AHEAD\`):
 
 \`\`\`
-git add -A && git commit -m "Migrate to kortix_version 2 (kortix.yaml) and the root layout"
+git add -A && git commit -m "Upgrade to kortix_version 3"
 git push origin HEAD
-kortix 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>"
+kortix 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>"
 \`\`\`
 
 If the push is rejected because the remote session branch moved, \`git fetch origin\` then \`git push --force-with-lease origin HEAD\` — your own session branch only, never any other branch.
 
-Then verify the CR actually carries your diff: run \`kortix cr diff <number>\` — 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).
+Then 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).
 
-Do **not** run \`kortix cr merge\`. This is a human-reviewed change like any other — 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.`;
+Do **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.`;

package/dist/customize/migrate-to-v2/upgrade-defs.d.ts

@@ -6,7 +6,7 @@
  * review (never merged by the agent). Adding a new upgrade = adding an entry
  * here; the view renders whatever is applicable.
  */
-import type { ManifestVersion } from '../../internal/lib/manifest-version.js';
+import { type ManifestVersion } from '../../internal/lib/manifest-version.js';
 export interface ProjectUpgradeContext {
     /** `null` while the manifest read hasn't resolved. */
     manifestVersion: ManifestVersion | null;

package/dist/customize/migrate-to-v2/upgrade-defs.js

@@ -6,14 +6,15 @@
  * review (never merged by the agent). Adding a new upgrade = adding an entry
  * here; the view renders whatever is applicable.
  */
-import { MIGRATE_TO_V2_PROMPT } from './migration-prompt.js';
+import { manifestNeedsUpgrade } from '../../internal/lib/manifest-version.js';
+import { MIGRATE_TO_V3_PROMPT } from './migration-prompt.js';
 export const PROJECT_UPGRADES = [
     {
-        id: 'manifest-v2',
-        title: 'Migrate manifest to v2 (kortix.yaml)',
-        description: 'Converts the v1 kortix.toml into the governance-first kortix.yaml, refreshes platform-managed skills to the latest marketplace baseline, and opens a change request for review.',
-        applicable: (ctx) => ctx.manifestVersion === 1,
-        prompt: MIGRATE_TO_V2_PROMPT,
+        id: 'manifest-v3',
+        title: 'Upgrade manifest to v3 (kortix.yaml)',
+        description: 'Moves kortix.toml or a version 2 kortix.yaml to version 3: the project registers skills, tools, commands and extensions, and each agent enables them by name. Refreshes platform-managed skills and opens a change request for review.',
+        applicable: (ctx) => manifestNeedsUpgrade(ctx.manifestVersion),
+        prompt: MIGRATE_TO_V3_PROMPT,
     },
 ];
 export function applicableUpgrades(ctx) {

package/dist/customize/migrate-to-v2/upgrade-view.js

@@ -5,7 +5,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  * halves:
  *
  *  1. The registry (`upgrade-defs.ts`): known upgrades with a detection rule
- *     (today: the v1→v2 manifest migration). Rows appear only while
+ *     (today: the v1/v2 → v3 manifest upgrade). Rows appear only while
  *     applicable and disappear for good once done.
  *  2. A freeform one-off runner: describe a single change ("bump X",
  *     "restructure Y") and a session makes it and opens a change request —
@@ -95,9 +95,9 @@ export const DEFAULT_UPGRADES_COPY = {
     oneOffPlaceholder: "e.g. Rename the release-bot agent to deploy-bot everywhere it's referenced",
     runUpgrade: 'Run upgrade',
     upgrades: {
-        'manifest-v2': {
-            title: 'Migrate manifest to v2 (kortix.yaml)',
-            description: 'Converts the v1 kortix.toml into the governance-first kortix.yaml, refreshes platform-managed skills to the latest marketplace baseline, and opens a change request for review.',
+        'manifest-v3': {
+            title: 'Upgrade manifest to v3 (kortix.yaml)',
+            description: 'Moves kortix.toml or a version 2 kortix.yaml to version 3: the project registers skills, tools, commands and extensions, and each agent enables them by name. Refreshes platform-managed skills and opens a change request for review.',
         },
     },
 };
@@ -143,9 +143,9 @@ export function UpgradesView({ projectId }) {
             oneOffPlaceholder: t('oneOffPlaceholder'),
             runUpgrade: t('runUpgrade'),
             upgrades: {
-                'manifest-v2': {
-                    title: t('manifestV2.title'),
-                    description: t('manifestV2.description'),
+                'manifest-v3': {
+                    title: t('manifestV3.title'),
+                    description: t('manifestV3.description'),
                 },
             },
         } }));

package/dist/customize/migrate-to-v2/use-run-upgrade.d.ts

@@ -1,9 +1,9 @@
 /**
  * useRunUpgrade — start any agent-led upgrade session from Customize: mint a
  * fresh session, stash the given prompt as its first message, close the
- * overlay, and drop the user into the thread. The generic engine behind both
- * the registry entries in `upgrade-defs.ts` and the one-off prompt runner;
- * `useMigrateToV2` is the v2-specific wrapper kept for its button.
+ * overlay, and drop the user into the thread. The engine behind the registry
+ * entries in `upgrade-defs.ts`, the one-off prompt runner and the sidebar
+ * upgrade alert.
  *
  * Deliberately does NOT pass `agent_name` — the session boots the project's
  * default agent (the one with git/CR powers).

package/dist/customize/providers/provider-accordion.js

@@ -24,10 +24,11 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
  * The pieces under `// ─── View` are pure (props only) so they render under
  * `renderToStaticMarkup`; `ProviderAccordion` owns every hook.
  */
-import { ArrowSquareOutIcon, CaretDownIcon, MagnifyingGlassIcon, XIcon, } from '@phosphor-icons/react';
+import { ArrowSquareOutIcon, CaretDownIcon, CreditCardIcon, MagnifyingGlassIcon, XIcon, } from '@phosphor-icons/react';
 import { useMemo, useState } from 'react';
 import { AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogTitle, } from '../../primitives/alert-dialog.js';
 import { Button } from '../../primitives/button.js';
+import { useModelConnectionGate } from '../../session/models/use-model-connection-gate.js';
 import { Input } from '../../primitives/input.js';
 import { InputGroupSearch, InputGroupSearchClear, InputGroupSearchIcon, InputGroupSearchInput, } from '../../primitives/input-group.js';
 import Loading from '../../primitives/loading.js';
@@ -152,6 +153,14 @@ function SignInSubRows({ projectId, entry, canWrite, }) {
                         ? t('signingIn', { name: sub.name })
                         : `${t('subscription', { plan: sub.plan })} · ${t('notConnected')}` }), waiting ? (_jsx("div", { className: "border-border border-t py-3", children: _jsx(DeviceCode, { name: sub.name, code: sign.challenge?.code ?? null, url: sign.challenge?.url ?? null, onCopy: copyCode }) })) : null, sign.error ? (_jsx("p", { role: "alert", className: "text-destructive pb-1.5 text-xs text-pretty", children: sign.error })) : null, _jsx(AlertDialog, { open: confirmDisconnect, onOpenChange: setConfirmDisconnect, children: _jsxs(AlertDialogContent, { children: [_jsxs(AlertDialogHeader, { children: [_jsx(AlertDialogTitle, { children: t('disconnectTitle', { plan: sub.plan }) }), _jsx(AlertDialogDescription, { children: t('disconnectBody') })] }), _jsxs(AlertDialogFooter, { children: [_jsx(AlertDialogCancel, { children: t('cancel') }), _jsx(AlertDialogAction, { variant: "destructive", disabled: sign.disconnect.isPending, onClick: () => sign.disconnect.mutate(), children: t('disconnect') })] })] }) })] }));
 }
+/** Opens the plan dialog. Nothing when billing is off: no plan to sell. */
+function ManagedUpgradeButton({ projectId }) {
+    const t = useTranslations('sessionUi.modelGate');
+    const { openUpgrade, showUpgradeOption } = useModelConnectionGate(undefined, { projectId });
+    if (!showUpgradeOption)
+        return null;
+    return (_jsxs(Button, { type: "button", size: "xs", className: "shrink-0", onClick: openUpgrade, children: [_jsx(CreditCardIcon, { className: "size-3.5 shrink-0" }), t('upgrade')] }));
+}
 /** What an open card holds, by how the provider connects. */
 function ExpandedBody({ projectId, entry, status, keyConnected, canWrite, enabled, pooled, }) {
     const t = useTranslations('providerSheet');
@@ -161,7 +170,13 @@ function ExpandedBody({ projectId, entry, status, keyConnected, canWrite, enable
     const enable = status !== 'none' ? (_jsx(EnableSubRow, { projectId: projectId, entry: entry, canWrite: canWrite, enabled: enabled })) : null;
     let content;
     if (method === 'included' || (entry.envVars.length === 0 && !SUBSCRIPTION_BY_PROVIDER[entry.id])) {
-        content = _jsx(AccordionSubRow, { children: entry.hint });
+        content = (_jsx(AccordionSubRow
+        // Kortix with no servable model is the upgrade story: the row says so,
+        // so it carries the way out too.
+        , { 
+            // Kortix with no servable model is the upgrade story: the row says so,
+            // so it carries the way out too.
+            action: entry.managed && entry.models.length === 0 ? _jsx(ManagedUpgradeButton, { projectId: projectId }) : null, children: entry.hint }));
     }
     else if (pooled.pooledSecretsEnabled && pooled.accountId && entry.id === 'openai') {
         content = (_jsxs("div", { className: "border-border space-y-3 border-t py-3", children: [_jsx("p", { className: "text-foreground text-xs font-medium", children: tPooled('chatGptAccounts') }), _jsx(AccountSecretResourcesPanel, { accountId: pooled.accountId, projectId: projectId, providerId: "codex", providerName: "ChatGPT Plus/Pro", envVar: "CODEX_AUTH_JSON", canWrite: true, oauth: { projectId, onConnected: () => undefined } }), _jsx(ChatGptSubscriptionConnect, { projectId: projectId, onConnected: () => undefined, legacyOnly: true })] }));

package/dist/customize/sections/component/channel-access-panel.d.ts

@@ -0,0 +1,16 @@
+import { type ChannelAccessPlatform, type ChannelUser } from '../../../internal/hooks/channels/use-channels-installations.js';
+/** What differs per platform. The `copy` values are `connectorPages` keys. */
+export declare const CHANNEL_ACCESS: Record<ChannelAccessPlatform, {
+    /** One typed user id, trimmed. Null for anything else. */
+    parseUserId: (raw: string) => string | null;
+    idPlaceholder: string;
+    idInputMode: 'numeric' | 'text';
+    copy: Record<'descriptionKey' | 'emptyDescription' | 'loadError' | 'addByIdHint' | 'addByIdInvalid' | 'removeDescription', string>;
+}>;
+/** First and last name, else @username, else the id. */
+export declare function channelUserName(user: Pick<ChannelUser, 'user_id' | 'username' | 'first_name' | 'last_name'>): string;
+export declare function ChannelAccessPanel({ projectId, platform, onDone, }: {
+    projectId: string;
+    platform: ChannelAccessPlatform;
+    onDone: () => void;
+}): import("react").JSX.Element;

package/dist/customize/sections/component/channel-access-panel.js

@@ -0,0 +1,146 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * Who may talk to a project's chat bot, as cards: the people who messaged
+ * the bot and wait to be allowed, the allowed users, and an add-by-ID field.
+ * Every action saves at once. The API adds or removes one id per call, so two
+ * admins never overwrite each other's list. `CHANNEL_ACCESS` holds what differs
+ * per platform. Its copy keys stay in this file, which binds `connectorPages`,
+ * so scripts/gen-i18n-catalog.mjs copies them into the bundled catalog.
+ */
+import { AccessRow } from '../../../access/access/access-row.js';
+import { Button } from '../../../primitives/button.js';
+import { ConfirmDialog } from '../../../primitives/confirm-dialog.js';
+import { CountBadge } from '../../../primitives/count-badge.js';
+import { EmptyArt } from '../../../primitives/empty-art.js';
+import { EmptyState } from '../../../primitives/empty-state.js';
+import { ErrorState } from '../../../primitives/error-state.js';
+import { Field, FieldDescription, FieldLabel } from '../../../primitives/field.js';
+import { Input } from '../../../primitives/input.js';
+import { ModalBody, ModalDescription, ModalFooter, ModalHeader, ModalTitle } from '../../../primitives/modal.js';
+import { Skeleton } from '../../../primitives/skeleton.js';
+import { errorToast } from '../../../primitives/toast.js';
+import { UserAvatar } from '../../../primitives/user-avatar.js';
+import { useAllowChannelUser, useChannelUserPhoto, useChannelUsers, useDismissChannelAccessRequest, useRemoveChannelUser, } from '../../../internal/hooks/channels/use-channels-installations.js';
+import { useTranslations } from '../../../i18n/index.js';
+import { CHANNELS } from '../../../_vendor/kortix-shared.js';
+import { UsersIcon } from '@phosphor-icons/react';
+import { useEffect, useId, useRef, useState } from 'react';
+/** What differs per platform. The `copy` values are `connectorPages` keys. */
+export const CHANNEL_ACCESS = {
+    telegram: {
+        parseUserId: (raw) => {
+            const id = raw.trim();
+            return CHANNELS.telegram.access.userId.test(id) ? id : null;
+        },
+        idPlaceholder: CHANNELS.telegram.access.idPlaceholder,
+        idInputMode: CHANNELS.telegram.access.idInputMode,
+        copy: {
+            descriptionKey: 'telegramUsersDescription',
+            emptyDescription: 'telegramUsersEmptyDescription',
+            loadError: 'telegramUsersLoadError',
+            addByIdHint: 'telegramAddByIdHint',
+            addByIdInvalid: 'telegramAddByIdInvalid',
+            removeDescription: 'telegramRemoveDescription',
+        },
+    },
+};
+/** First and last name, else @username, else the id. */
+export function channelUserName(user) {
+    const full = [user.first_name, user.last_name].filter(Boolean).join(' ').trim();
+    return full || (user.username ? `@${user.username}` : user.user_id);
+}
+const onError = (error) => errorToast(error.message);
+export function ChannelAccessPanel({ projectId, platform, onDone, }) {
+    const t = useTranslations('hardcodedUi.i18nComplete');
+    const tPages = useTranslations('connectorPages');
+    const { copy } = CHANNEL_ACCESS[platform];
+    const users = useChannelUsers(projectId, platform, true);
+    const remove = useRemoveChannelUser(platform);
+    const [removing, setRemoving] = useState(null);
+    const [confirmOpen, setConfirmOpen] = useState(false);
+    const allowedHeading = useRef(null);
+    const requests = users.data?.requests ?? [];
+    const allowed = users.data?.allowed ?? [];
+    const removingName = removing ? channelUserName(removing) : '';
+    return (_jsxs(_Fragment, { children: [_jsxs(ModalHeader, { children: [_jsx(ModalTitle, { children: t.raw('text2c3059c25723') }), _jsx(ModalDescription, { children: tPages(copy.descriptionKey) })] }), _jsxs(ModalBody, { children: [users.isError && !users.data ? (_jsx(ErrorState, { size: "sm", title: tPages(copy.loadError), action: _jsx(Button, { variant: "outline", size: "sm", onClick: () => void users.refetch(), children: t.raw('textd8b8392e2c54') }) })) : (
+                    // The lists scroll; the add field and the footer stay put. Capped like
+                    // the channel list in channels-view.tsx, so the footer stays on screen
+                    // at the 720 × 480 desktop minimum, where this modal is a bottom sheet.
+                    _jsxs("div", { className: "max-h-[min(45vh,calc(100dvh-21rem))] space-y-4 overflow-y-auto", children: [requests.length > 0 ? (_jsxs("section", { className: "space-y-2", children: [_jsxs("h3", { className: "text-muted-foreground flex items-center gap-2 px-1 text-xs font-medium", children: [tPages('channelAccessRequestsTitle'), _jsx(CountBadge, { count: requests.length, tone: "waiting" })] }), _jsx("ul", { className: "space-y-2", children: requests.map((user) => (_jsx(RequestRow, { projectId: projectId, platform: platform, user: user }, user.user_id))) })] })) : null, _jsxs("section", { className: "space-y-2", children: [_jsxs("h3", { ref: allowedHeading, tabIndex: -1, className: "text-muted-foreground flex items-center gap-2 px-1 text-xs font-medium outline-none", children: [tPages('channelAccessAllowedTitle'), allowed.length > 0 ? _jsx(CountBadge, { count: allowed.length }) : null] }), users.isPending ? (_jsxs("div", { className: "space-y-2", children: [_jsx(Skeleton, { className: "h-12" }), _jsx(Skeleton, { className: "h-12" })] })) : allowed.length === 0 ? (_jsx(EmptyState, { size: "sm", media: _jsx(EmptyArt, { icon: UsersIcon }), title: tPages('channelAccessEmptyTitle'), description: tPages(copy.emptyDescription) })) : (_jsx("ul", { className: "space-y-2", children: allowed.map((user) => {
+                                            const name = channelUserName(user);
+                                            return (_jsx(ChannelUserRow, { projectId: projectId, platform: platform, user: user, pending: remove.isPending && remove.variables?.userId === user.user_id, kebabLabel: t('text33da220b1a34', { value0: name }), kebab: [
+                                                    {
+                                                        label: t.raw('textc3812fc4acb8'),
+                                                        variant: 'destructive',
+                                                        onSelect: () => {
+                                                            setRemoving(user);
+                                                            setConfirmOpen(true);
+                                                        },
+                                                    },
+                                                ] }, user.user_id));
+                                        }) }))] })] })), _jsx(AddByIdField, { projectId: projectId, platform: platform })] }), _jsx(ModalFooter, { className: "pt-2 pb-5", children: _jsx(Button, { type: "button", variant: "outline-ghost", onClick: onDone, children: t.raw('text11a6767d5674') }) }), _jsx(ConfirmDialog, { open: confirmOpen, onOpenChange: setConfirmOpen, title: tPages('channelAccessRemoveTitle', { name: removingName }), description: tPages(copy.removeDescription, { name: removingName }), confirmLabel: t.raw('textc3812fc4acb8'), confirmVariant: "destructive", isPending: remove.isPending, onConfirm: () => {
+                    if (!removing)
+                        return;
+                    remove.mutate({ projectId, userId: removing.user_id }, {
+                        onSuccess: () => {
+                            setConfirmOpen(false);
+                            allowedHeading.current?.focus();
+                        },
+                        onError,
+                    });
+                } })] }));
+}
+function RequestRow({ projectId, platform, user, }) {
+    const t = useTranslations('hardcodedUi.i18nComplete');
+    const tPages = useTranslations('connectorPages');
+    const allow = useAllowChannelUser(platform);
+    const dismiss = useDismissChannelAccessRequest(platform);
+    const name = channelUserName(user);
+    const busy = allow.isPending || dismiss.isPending;
+    const vars = { projectId, userId: user.user_id };
+    return (_jsx(ChannelUserRow, { projectId: projectId, platform: platform, user: user, pending: busy, actions: _jsx(Button, { size: "sm", disabled: busy, "aria-busy": allow.isPending, "aria-label": tPages('channelAccessAllowAria', { name }), onClick: () => allow.mutate(vars, { onError }), children: t.raw('texte213c161d5ce') }), kebabLabel: t('text33da220b1a34', { value0: name }), kebab: [{ label: t.raw('text48845bff334a'), onSelect: () => dismiss.mutate(vars, { onError }) }] }));
+}
+/** One person as an access card: photo or initials, name, @username, the id in mono. */
+function ChannelUserRow({ projectId, platform, user, ...row }) {
+    const name = channelUserName(user);
+    const nameIsId = name === user.user_id;
+    const handle = user.username ? `@${user.username}` : null;
+    return (_jsx(AccessRow, { leading: _jsx(ChannelUserAvatar, { projectId: projectId, platform: platform, user: user, name: name }), title: nameIsId ? _jsx("span", { className: "font-mono tabular-nums", children: name }) : name, metaParts: [
+            handle && handle !== name ? handle : null,
+            nameIsId ? null : _jsx("span", { className: "font-mono tabular-nums", children: user.user_id }),
+        ].filter(Boolean), ...row }));
+}
+function ChannelUserAvatar({ projectId, platform, user, name, }) {
+    const { data: photo } = useChannelUserPhoto(projectId, platform, user.user_id, user.photo_version, true);
+    const [url, setUrl] = useState(null);
+    // The object URL lives as long as this blob: a new photo or an unmount revokes it.
+    useEffect(() => {
+        if (!photo)
+            return;
+        const next = URL.createObjectURL(photo);
+        setUrl(next);
+        return () => {
+            URL.revokeObjectURL(next);
+            setUrl(null);
+        };
+    }, [photo]);
+    // The id keys the fallback colour, as an email does for a member.
+    return _jsx(UserAvatar, { email: user.user_id, name: name, avatarUrl: url, size: "md" });
+}
+function AddByIdField({ projectId, platform }) {
+    const t = useTranslations('hardcodedUi.i18nComplete');
+    const tPages = useTranslations('connectorPages');
+    const { parseUserId, idPlaceholder, idInputMode, copy } = CHANNEL_ACCESS[platform];
+    const allow = useAllowChannelUser(platform);
+    const inputId = useId();
+    const [value, setValue] = useState('');
+    const id = parseUserId(value);
+    const invalid = value.trim() !== '' && !id;
+    return (_jsx("form", { onSubmit: (event) => {
+            event.preventDefault();
+            if (!id)
+                return;
+            allow.mutate({ projectId, userId: id }, { onSuccess: () => setValue(''), onError });
+        }, children: _jsxs(Field, { children: [_jsx(FieldLabel, { htmlFor: inputId, children: tPages('channelAccessAddByIdLabel') }), _jsxs("div", { className: "flex gap-2", children: [_jsx(Input, { id: inputId, size: "sm", inputMode: idInputMode, autoComplete: "off", placeholder: idPlaceholder, value: value, onChange: (event) => setValue(event.target.value), "aria-invalid": invalid }), _jsx(Button, { type: "submit", variant: "outline", disabled: !id || allow.isPending, "aria-busy": allow.isPending, children: t.raw('text9fd728c66c9a') })] }), _jsx(FieldDescription, { children: invalid ? tPages(copy.addByIdInvalid) : tPages(copy.addByIdHint) })] }) }));
+}