@metabase/rde 0.5.1 → 0.5.3

package/README.md

@@ -34,7 +34,7 @@ The wizard shows its checklist first (`✓` done, `○` to do, `↑` done but be
 ○ Install the Metabase CLI
 ○ Install Metabase
 ○ Start Metabase
-○ Install the rde and data-app skills for your coding agents
+○ Install the metabase-rde skill for your coding agents
 ○ Create the admin user
 ○ Connect the Metabase CLI
 ○ Enable transforms
@@ -60,7 +60,7 @@ The git step reads `–` until a license with remote sync is active; it is check
 | Install the Metabase CLI | `@metabase/cli` (`mb`) at the `latest` dist-tag, with the package manager that installed `rde`; an installed `mb` older than what the dist-tag names now is updated. `rde status` and `rde doctor` check only what is installed and ask no registry |
 | Install Metabase | **Docker** when it is available: pulls the major line of the newest Metabase Enterprise release, such as `metabase/metabase-enterprise:v1.65.x` (or `--image`), and creates the container. **Jar** otherwise, or with `--runtime jar`: downloads the newest enterprise release (or the tag or `.jar` path given as `--jar`) into `~/.rde/jars/` and runs it with your Java. [Metabase versions](#metabase-versions) says how the release is found. Either way on port 23000, or the first free port above it that nothing else claims, or `--port` |
 | Start Metabase | Starts the container or the jar and waits for `/api/health`, showing Metabase's own progress |
-| Install the rde and data-app skills | The `metabase-data-apps` skill, one skill with a guide per data-app task (setup, routing, actions, semantic layer, migrate), from the `skills/metabase-data-apps/v1` folder of the `main` branch of `metabase/agent-skills`, then the `metabase-rde` skill from the `skills/metabase-rde/v1` folder of the same branch (its data-app reference settles what an app needs on an rde machine and hands the build to `metabase-data-apps`), for the coding agents you pick at a terminal, from the ones found on this machine (OpenCode, Claude Code, Codex, Cursor, Gemini CLI, Windsurf). When none is found, the step is skipped and says how to add the skills once an agent is installed; `rde` installs no agent. Without a terminal, or with `--yes`, every agent found gets the skills; `--agents` picks a set ahead of time (the skills are installed for them whether or not they are on the machine yet), `--skip-agents` none; `RDE_SKILL_SOURCE` installs both from another branch URL or a local checkout of `metabase/agent-skills`. The `v1` folder of `metabase-data-apps` is the data-app contract version Metabase serves, the same whatever Metabase version the instance runs; a breaking contract change gets a folder of its own (`v2`, …), and the guide for migrating an app Metabase marks Outdated moves it to the newer one. Installed skills whose directory changed on its branch since are installed again, without a question when every detected agent already has them all, and copies of the earlier per-task data-app skills (`metabase-data-app-setup`, `-routing`, `-actions`, `-semantic-layer`, `-migrate`) that the skills lock attributes to `metabase/metabase`, whoever installed them, are removed once `metabase-data-apps` is in, so the two never compete; a copy also installed for an agent that has no `metabase-data-apps` after the run stays, with a warning naming those agents and the `rde init --only agents-skills --agents <…>` command that replaces it. Copies of `rde` and `rde-data-apps`, the two skills an earlier rde installed in place of `metabase-rde`, are removed the same way once `metabase-rde` is in, wherever they came from. The skills are installed globally, not per instance, so every instance on the machine shares one set |
+| Install the metabase-rde skill | The `metabase-rde` skill from the `skills/metabase-rde/v1` folder of the `main` branch of `metabase/agent-skills` (its data-apps reference settles what an app needs on an rde machine and hands the build to the `mb` CLI's data-app skills, `mb skills get data-app`), for the coding agents you pick at a terminal, from the ones found on this machine (OpenCode, Claude Code, Codex, Cursor, Gemini CLI, Windsurf). When none is found, the step is skipped and says how to add the skill once an agent is installed; `rde` installs no agent. Without a terminal, or with `--yes`, every agent found gets the skill; `--agents` picks a set ahead of time (the skill is installed for them whether or not they are on the machine yet), `--skip-agents` none; `RDE_SKILL_SOURCE` installs it from another branch URL or a local checkout of `metabase/agent-skills`. An installed skill whose directory changed on its branch since is installed again, without a question when every detected agent already has it. Copies of `rde`, `rde-data-apps`, and `metabase-data-apps`, the skills an earlier rde installed, are removed once `metabase-rde` is in, wherever they came from, and so are copies of the earlier per-task data-app skills (`metabase-data-app-setup`, `-routing`, `-actions`, `-semantic-layer`, `-migrate`) that the skills lock attributes to `metabase/metabase`, whoever installed them, so none competes with it; a copy also installed for an agent that has no `metabase-rde` after the run stays, with a warning naming those agents and the `rde init --only agents-skills --agents <…>` command that replaces it. The skill is installed globally, not per instance, so every instance on the machine shares one copy |
 | Create the admin user | `admin@metabase.local` with a generated password that `rde credentials` shows, or your own with `--admin prompted`, see [Credentials](#credentials) |
 | Connect the Metabase CLI | Creates an API key named `rde` and logs `mb` in with it under the profile `default`, so plain `mb` uses the instance; when `default` already points at another Metabase it asks first, see [The `mb` profile](#the-mb-profile); a key Metabase rejects is replaced |
 | Enable transforms | Turns transforms on, unless someone already set them either way: turned off in the admin settings, they stay off on every later `rde init`, and the admin settings turn them back on |
@@ -76,7 +76,7 @@ The second run on the same machine detects every step as done and prints the sum
 ┌  rde init
 ✓ Check this machine
 ✓ Install the Metabase CLI
-✓ Install the rde and data-app skills for your coding agents
+✓ Install the metabase-rde skill for your coding agents
 ✓ Install Metabase
 ✓ Start Metabase
 ✓ Create the admin user
@@ -166,6 +166,7 @@ A new instance runs the newest release that Metabase's release feed (`https://st
 | `rde open` | Opens the instance in the browser |
 | `rde db add` | The database wizard: pick the stubs to connect when the content uses databases not connected yet, otherwise (or after them) pick the engine, paste a connection string or fill the fields, review, test, add. `rde db add --url <connection string> [--name <display name>]` asks nothing: it reads the engine from the string (`--engine` for one that fits several), tests it and adds it, which is how a script or a coding agent connects a database without a terminal; `--url -` reads the string from stdin; a `--name` that is a stub's connects that stub |
 | `rde db list` | The connected databases and the stubs still waiting for a connection (`stub` in `--json`); `--json` for scripts; a bare `rde db` does the same |
+| `rde create data-app` | Opens a coding agent that has the `metabase-rde` skill in the content repository, with a first message asking it to plan a data app with you: it asks what the app is for before it builds anything. Asked which agent when several have the skill; `--agent <name>` picks one. An editor (Cursor, Windsurf) takes no first message, so the command prints it to paste. Needs a terminal and remote sync set up |
 | `rde doctor` | One table of checks with a fix hint per failure; `--fix` re-runs the init steps behind them; `--json` for scripts and the rde skill (every row's `id`, `status`, `detail`, `hint`, and `fix`: the `rde` command that repairs it, or null when you have to act); exit 1 while anything fails |
 | `rde upgrade` | Moves the instance to a newer Metabase after backing up its data; see [Upgrading](#upgrading) |
 | `rde uninstall` | Removes the instance, its data, and the `mb` profile; see [Resetting](#resetting) |
@@ -266,7 +267,7 @@ rde init --license-token '$RDE_LICENSE_TOKEN' …
 
 `rde upgrade` moves the instance to a newer Metabase without losing its application database. It makes sure the instance is running and reads the version it is on, fetches the target, and stops there with `Already on …` when the target is what the instance already runs. Otherwise it shows the running version, the target, and the backup path, asks once (`--yes` skips the question; without a terminal `--yes` is required), and then stops Metabase, copies the whole `data/` directory to `~/.rde/instances/default/backups/<timestamp>/`, switches the instance to the target, starts it, waits for health, and records the new version. Metabase migrates its application database forward on that first start.
 
-A move to another major version (65 to 66, say) is named before the backup with `This moves Metabase from 65 to 66`, ahead of the same question. A target that names no release shows its version only once it runs, and the plan says so: a major line (`:v1.66.x`) still names its major, so the move is named before the backup all the same, while `:latest` or a jar path names nothing, so the line comes after the start instead. Either way, once the new major runs, `rde upgrade` runs the skills step, which installs again every skill whose folder changed on its branch; at a terminal it asks which agents get them like `rde init` does, and with `--yes` every agent found gets them.
+A move to another major version (65 to 66, say) is named before the backup with `This moves Metabase from 65 to 66`, ahead of the same question. A target that names no release shows its version only once it runs, and the plan says so: a major line (`:v1.66.x`) still names its major, so the move is named before the backup all the same, while `:latest` or a jar path names nothing, so the line comes after the start instead. Either way, once the new major runs, `rde upgrade` runs the skills step, which installs the skill again when its folder changed on its branch; at a terminal it asks which agents get it like `rde init` does, and with `--yes` every agent found gets it.
 
 For a Docker instance the target is an image ref (`--to <image ref>`; by default, for an image of `metabase/metabase-enterprise`, `metabase/metabase-enterprise-head`, or `metabase/metabase`, the major line of the newest release, found the way `init` finds it, whatever tag the instance ran before: `:latest`, an older major line, or the same line), the pulled image is compared by id with the one the container runs, and the container is removed and created again from the target with the same port and mount and the environment rde sets now. An image from any other repository (a registry of your own, an image you built) is pulled again under its own ref, and the plan says so. The default target follows the feed rules of [Metabase versions](#metabase-versions): a feed that lists no release of 65 or newer, or cannot be read, stops the upgrade before it starts Metabase or pulls anything. With `RDE_DEV=1` the default target is the instance's own image. When the target is the image already running, a container created under another ref of it (`:latest` that names the same image as the line, say) or one that keeps variables rde sets otherwise now (the staging store of development mode, say) is still created again from that image under the target's ref, with no backup since nothing migrates; `rde doctor` names a container with such variables, with `rde upgrade` as the fix. A build of master (`metabase/metabase-enterprise-head:latest`, the development image) reports a major ahead of every release, so `rde upgrade` refuses it as a downgrade; `rde doctor` names one outside development mode, and the way onto a release is `rde uninstall`, then `rde init`, while `RDE_DEV=1` keeps running it. For a jar instance the target is `latest` (the default, the newest release), a release tag, or a `.jar` path; a release is downloaded into `~/.rde/jars/` before the question, and the instance's `runtime.source` is switched to it.
 
@@ -295,7 +296,7 @@ With the local `content.git` remote, that repository lives in the instance direc
 ```sh
 rde uninstall                  # container or process, mb profile, ~/.rde/instances/default
 rde uninstall --keep-data      # container or process and profile only; the data and secrets.json stay, and `rde init` reinstalls from them
-rde uninstall --remove-skill   # also the metabase-rde and metabase-data-apps skills (and the older rde and rde-data-apps) from your coding agents
+rde uninstall --remove-skill   # also the metabase-rde skill (and the older rde, rde-data-apps, and metabase-data-apps) from your coding agents
 rde uninstall --remove-image   # also the Docker images or the downloaded jar (otherwise they stay for the next init)
 rde uninstall --yes --force    # also deletes commits in content.git that your working directory has not pulled
 ```
@@ -309,14 +310,14 @@ Running it twice is a no-op. It also works with no `~/.rde` at all, so a leftove
 | Variable | What it does |
 | --- | --- |
 | `RDE_HOME` | Where rde keeps its state instead of `~/.rde`; a relative path is resolved against the working directory |
-| `RDE_SKILL_SOURCE` | Development only: the `metabase/agent-skills` branch or checkout the `metabase-rde` and `metabase-data-apps` skills are installed from (from its `skills/metabase-rde/v1` and `skills/metabase-data-apps/v1` folders) instead of the `main` branch: a GitHub URL that names a branch (`…/tree/<branch>`) or the root of a local checkout, so they can be tried before they are pushed |
+| `RDE_SKILL_SOURCE` | Development only: the `metabase/agent-skills` branch or checkout the `metabase-rde` skill is installed from (from its `skills/metabase-rde/v1` folder) instead of the `main` branch: a GitHub URL that names a branch (`…/tree/<branch>`) or the root of a local checkout, so it can be tried before it is pushed |
 | `RDE_DEV` | Development only: `1` runs instances on the enterprise build of master and checks license tokens against the staging store; `bin/rde-dev` sets it |
 
 An empty value counts as unset.
 
 ## Troubleshooting
 
-Start with `rde doctor`. It checks the machine (platform, Node, git, Docker, Java, every `mb` on `PATH`, and whether a newer rde is released, the one check that asks the npm registry and gives up after a few seconds), the instance (the container or the jar process, port, health, Metabase version, admin user, admin password, whether Metabase accepts the API key, the secrets file's modes, no secret left in `state.json`, `mb` profile and the URL it points at, license, databases, remote sync), the `MB_PROFILE`, `MB_URL`, and `MB_API_KEY` variables when set, the other Metabases `mb` knows, the skill for each detected coding agent, every copy of the skill, and the data-app skills, one row each with ✓, ✗, or – and a hint under every ✗. A row marked `!` is a note: nothing fails, but it changes where `mb` goes. Of Docker and Java, the one the instance does not use is `–` when missing; the one it uses is ✗.
+Start with `rde doctor`. It checks the machine (platform, Node, git, Docker, Java, every `mb` on `PATH`, and whether a newer rde is released, the one check that asks the npm registry and gives up after a few seconds), the instance (the container or the jar process, port, health, Metabase version, admin user, admin password, whether Metabase accepts the API key, the secrets file's modes, no secret left in `state.json`, `mb` profile and the URL it points at, license, databases, remote sync), the `MB_PROFILE`, `MB_URL`, and `MB_API_KEY` variables when set, the other Metabases `mb` knows, the skill for each detected coding agent, and every copy of the skill, one row each with ✓, ✗, or – and a hint under every ✗. A row marked `!` is a note: nothing fails, but it changes where `mb` goes. Of Docker and Java, the one the instance does not use is `–` when missing; the one it uses is ✗.
 
 ```
 ✓ container    rde-metabase-default stopped (metabase/metabase-enterprise:v1.65.x)
@@ -373,9 +374,7 @@ Start Docker (or `colima start`), or install Java, and run `rde init` again. `rd
                    plain `mb` uses prod (MB_PROFILE): prod.acme.example
 ```
 
-**The agent follows an old copy of the skill.** The `metabase-rde skill copies` row lists every copy of the skill the `skills` CLI knows, global and in the current directory's project, with where it came from, and fails when one did not come from rde's source (the branch is read from the `skills` lock file; against a local `RDE_SKILL_SOURCE` the copy's `SKILL.md` is compared with the checkout's `skills/metabase-rde/v1/SKILL.md`), and also fails while a global copy of `rde` or `rde-data-apps`, which `metabase-rde` replaces, is still there. With several copies it says which one Claude Code started in that directory loads (a personal skill wins over a project one). `rde init --only agents-skills` reinstalls the global copy and removes the replaced ones; restart the agent session afterwards.
-
-**The agent follows the wrong data-app skill.** The `data-app skills` row fails when `metabase-data-apps` is missing or its copy did not come from rde's source (against a local `RDE_SKILL_SOURCE`, the checkout's `skills/metabase-data-apps/v1/SKILL.md`), or when a copy of an earlier per-task data-app skill (`metabase-data-app-setup` and the like) that the skills lock attributes to `metabase/metabase` is still there, whoever installed it. `rde init --only agents-skills` (or `rde doctor --fix`) installs the skills and removes the copies `metabase-data-apps` replaces; a copy also installed for an agent that has no `metabase-data-apps` after the run stays, and the run names the `--agents` that let it go. Restart the agent session afterwards.
+**The agent follows an old copy of the skill.** The `metabase-rde skill copies` row lists every copy of the skill the `skills` CLI knows, global and in the current directory's project, with where it came from, and fails when one did not come from rde's source (the branch is read from the `skills` lock file; against a local `RDE_SKILL_SOURCE` the copy's `SKILL.md` is compared with the checkout's `skills/metabase-rde/v1/SKILL.md`), and also fails while a global copy of a skill `metabase-rde` replaces is still there: `rde`, `rde-data-apps`, or `metabase-data-apps`, or an earlier per-task data-app skill (`metabase-data-app-setup` and the like) that the skills lock attributes to `metabase/metabase`. With several copies it says which one Claude Code started in that directory loads (a personal skill wins over a project one). `rde init --only agents-skills` (or `rde doctor --fix`) reinstalls the global copy and removes the replaced ones; a replaced copy also installed for an agent that has no `metabase-rde` after the run stays, and the run names the `--agents` that let it go. Restart the agent session afterwards.
 
 **The license token is rejected.** Metabase checks the token with `token-check.metabase.com` before it saves it. `The license token was refused: <reason>` means the store turned the token down: check that you pasted the whole token and that its subscription is active. `The instance could not reach token-check.metabase.com to check the license token` means the check never got an answer: the container (or the jar) needs outbound network access to that host. At a terminal the step asks for the token again, and Enter skips the license and carries on without remote sync, data apps, and transform tests; without a terminal the run stops, and `rde init --from license` tries again.