rqbazan · Oct 18, 2026 · Oct 18, 2026 · Oct 18, 2026 · Oct 18, 2026
diff --git a/.changeset/readme-structure.md b/.changeset/readme-structure.md
@@ -0,0 +1,17 @@
+---
+"@rrlab/cli": patch
+"@rrlab/astro-plugin": patch
+"@rrlab/biome-plugin": patch
+"@rrlab/oxc-plugin": patch
+"@rrlab/ts-plugin": patch
+"@rrlab/tsdown-plugin": patch
+"@rrlab/vitest-plugin": patch
+"@rrlab/biome-config": patch
+"@rrlab/ts-config": patch
+"@rrlab/tsdown-config": patch
+"@variablelab/vland": patch
+"@variablelab/clibuddy": patch
+"@variablelab/loggy": patch
+---
+
+The README follows the Variable Lab README structure, and the tarball now includes the MIT `LICENSE`.
diff --git a/LICENSE b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 rcrd <ricardo@variable.land>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/README.md b/README.md
@@ -1,84 +1,26 @@
-# DX
+# dx
 
-Monorepo to hold tools made for DX.
+The monorepo of run-run and vland.
 
-## Packages
+## Projects
 
+- <img src="https://raw.githubusercontent.com/withvariablelab/dx/HEAD/run-run/cli/brand/sign-readme.svg" width="24" alt="" align="absmiddle">&nbsp;[run-run](run-run/cli): One way to run the scripts in a repo. [Project page](https://lab.variable.land/run-run).
+- <img src="https://raw.githubusercontent.com/withvariablelab/dx/HEAD/vland/cli/brand/sign-readme.svg" width="24" alt="" align="absmiddle">&nbsp;[vland](vland/cli): Starts a project in Variable Land. [Project page](https://lab.variable.land/vland).
 
-| Name      | Description                                           | Documentation                                                              |
-| --------- | ----------------------------------------------------- | -------------------------------------------------------------------------- |
-| `vland`   | CLI to init a new project in Variable Land            | [vland](./vland/cli/README.md) ([CLI reference](./vland/cli/CLI.md))       |
-| `run-run` | CLI + plugin ecosystem for scripts in Variable Land   | [run-run](./run-run/cli/README.md) ([CLI reference](./run-run/cli/CLI.md)) |
-| `shared`  | Internal utilities shared across both CLIs            | [clibuddy](./shared/clibuddy/README.md), [loggy](./shared/loggy/README.md) |
+## Repository
 
-The `run-run` ecosystem ships as opt-in pieces: the `@rrlab/cli` kernel + its official plugins (`@rrlab/<tool>-plugin`, listed in the [`@rrlab/cli` README](./run-run/cli/README.md#plugins)) + their shared config presets (`@rrlab/<tool>-config`). See [`run-run/CLAUDE.md`](./run-run/CLAUDE.md) for the architecture.
+- [`run-run/`](run-run): run-run. The CLI is in `cli/`, a plugin per tool in `*-plugin/` and the presets in `*-config/`. The [run-run README](run-run/cli/README.md#plugins) lists the plugins.
+- [`vland/`](vland): vland. The CLI is in `cli/`, and the templates it starts a project from are in `templates/`.
+- [`shared/`](shared): `@variablelab/clibuddy` and `@variablelab/loggy`, internal to the two CLIs.
 
+## Contributing
 
-## Usage
+The [contributing guide](docs/contributing.md) covers issues, pull requests and releases, and the [development guide](docs/development.md) covers setting up the repo and running its checks.
 
-To get started with any package, navigate to the respective package directory and follow the installation and usage instructions in its README.
+## License
 
-## Development
+[MIT](LICENSE).
 
-### Requirements
-
-To use this monorepo, you need to have the following tools installed:
-
-- [Node.js](https://nodejs.org) >= 24.0.0
-- [pnpm](https://pnpm.io) >= 10.0.0
-- [mise](https://mise.jdx.dev) >= 2025.3.3 <sup>(optional)</sup>
-
-### Setup
-
-1. Clone the repository:
-
-   ```bash
-   git clone git@github.com:withvariablelab/dx.git
-   ```
-
-2. Install dependencies:
-
-   ```bash
-   pnpm install
-   ```
-
-3. Run tests:
-
-   ```bash
-   pnpm test
-   ```
-
-### Commands
-
-This monorepo uses [Turborepo](https://turbo.build/repo/docs) to manage tasks. Here are some useful commands:
-
-- `pnpm build` - Build all packages
-- `pnpm test` - Run tests for all packages
-
-Additionally, the monorepo itself uses the CLIs [`run-run`](./run-run/cli/README.md) and [`vland`](./vland/cli/README.md):
-
-- `pnpm rr` - Run the `run-run` CLI in development mode
-- `pnpm vland` - Run the `vland` CLI in development mode
-
-If you have [mise](https://mise.jdx.dev) installed, you can use the following commands directly:
-
-- `rr` - Run the `run-run` CLI in development mode
-- `vland` - Run the `vland` CLI in development mode
-
-### Release
-
-This monorepo uses [Changesets](https://github.com/changesets/changesets) to manage releases. The [Changesets bot](https://github.com/changesets/bot) is also installed in the repository.
-
-**Preview Release**:
-
-To preview changes in any package, create a pull request using the branch pattern `feat/*` or `fix/*` or add a label `preview` to the PR. This triggers a special GitHub workflow that publishes the package with the changes to the npm registry under the tag `pr-<PR_NUMBER>`. To preview your changes, install the package with the corresponding tag:
-
-```bash
-pnpm add @variablelab/<package>@pr-123
-```
-
-For `@rrlab/*-plugin` packages, `rr plugins add` accepts the same `@<tag>` suffix and propagates it to the plugin's `@rrlab/*-config` sibling — falling back to `latest` for any sibling the preview didn't publish:
-
-```bash
-rr plugins add biome@pr-123
-```
+<p align="center">
+  <a href="https://lab.variable.land"><img src="https://cdn.jsdelivr.net/gh/withvariablelab/brand@v0.3.1/.github/readme/logo.svg" width="24" alt="" align="absmiddle">&nbsp;Variable Land</a>
+</p>
diff --git a/docs/contributing.md b/docs/contributing.md
@@ -0,0 +1,32 @@
+# Contributing
+
+dx takes bug reports, fixes and small features for run-run, vland and their packages. To set up the repo and run its checks, see the [development guide](development.md).
+
+## Issues
+
+- A bug report says what you ran, what you expected, what happened, and which Node version and package versions you use. `DEBUG=run-run:*` or `DEBUG=vland:*` before the command prints the debug log.
+- A new feature, a new plugin, or a change to a command, a template or the plugin contract starts as an issue before any pull request.
+
+## Pull requests
+
+1. Branch from `main` with a prefix: `feat/`, `fix/`, `docs/`, `chore/` or `test/`.
+2. Write commits as [Conventional Commits](https://www.conventionalcommits.org), such as `fix(oxc-plugin): stop installing a flaky oxlint-tsgolint`. The pull request title takes the same form, because it becomes the squash commit.
+3. A feature lands with a test of the happy path and at least one failure case, and a fix with a regression test.
+4. Run `pnpm rr check` and `pnpm test` before you push.
+5. A pull request from a `feat/` or `fix/` branch, or with the `preview` label, publishes a preview to npm, under the `pr-<number>` tag, of each package it changes and the packages that depend on them. The [development guide](development.md#preview-releases) shows how to install one.
+
+CI has to pass, and a maintainer squash-merges.
+
+## Changesets
+
+A change to what a package ships to npm needs a changeset. Run `pnpm changeset`, pick the packages and the bump (`patch` for a fix, `minor` for a feature, `major` for a breaking change), and write one sentence for the changelog. Changes to tests, CI, `decisions/` or these docs need none.
+
+The plugins take `@rrlab/cli` as a peer, and a changeset that bumps `@rrlab/cli` by `major` also lists every official plugin as `major`. [Decision 011](../decisions/011-cli-peer-bump-strategy.md) explains why.
+
+Nobody edits versions or `CHANGELOG.md` by hand, and nobody publishes from a clone.
+
+## Releases
+
+When changesets land on `main`, the Release job opens or updates a "chore: update versions" pull request as `vland-bot`. A maintainer merges it, and the next run on `main` publishes each new version to npm, with npm trusted publishing, and tags it.
+
+A new tag of `@rrlab/cli` or `@variablelab/vland` regenerates the `CLI.md` of both CLIs in a "chore: regenerate CLI docs" pull request, which a maintainer merges too.
diff --git a/docs/development.md b/docs/development.md
@@ -0,0 +1,79 @@
+# Development
+
+How to work on dx in a clone. The [contributing guide](contributing.md) covers how a change gets in.
+
+## Layout
+
+- [`run-run/`](../run-run): run-run. `cli/` is `@rrlab/cli`, the kernel and the `rr` command. Each `*-plugin/` wraps one tool, and each `*-config/` is a preset that a plugin installs. [`run-run/CLAUDE.md`](../run-run/CLAUDE.md) covers the architecture: the plugin contract and how to add or change a plugin.
+- [`vland/`](../vland): vland. `cli/` is `@variablelab/vland`, and `templates/` holds the projects `vland init` starts from.
+- [`shared/`](../shared): `@variablelab/clibuddy` and `@variablelab/loggy`, the internal packages both CLIs depend on.
+- [`decisions/`](../decisions): the architecture decisions, one file each.
+- `docs/`: this guide and the [contributing guide](contributing.md).
+
+The workspace is pnpm, the tasks run through [Turborepo](https://turborepo.com), and tsdown builds each package that has a build step.
+
+## Setup
+
+[mise](https://mise.jdx.dev) pins Node 24, pnpm and [usage](https://usage.jdx.dev) in `mise.toml`, locked in `mise.lock`. It also puts `node_modules/.bin` on the `PATH`, so `rr` and `vland` run by name.
+
+```sh
+git clone git@github.com:withvariablelab/dx.git
+cd dx
+mise install
+pnpm install
+```
+
+`pnpm install` also installs the git hooks, through lefthook.
+
+The published packages declare `engines.node` as `>=22.18.0`, except `@rrlab/biome-config` and `@rrlab/ts-config`, which hold only JSON presets and declare none. `mise.floor.toml` pins that floor, and `MISE_ENV=floor` runs the repo on it, as CI does:
+
+```sh
+MISE_ENV=floor mise install
+MISE_ENV=floor mise exec -- pnpm test
+```
+
+To raise the floor, change `mise.floor.toml` and every `engines.node` together, then run `MISE_ENV=floor mise lock`.
+
+## Tasks
+
+```sh
+pnpm build                       # build every package
+pnpm test                        # build, then run every package's tests
+pnpm rr check                    # format, lint and type check, with the repo's own rr
+pnpm rr jsc --fix                # apply Biome's fixes
+pnpm tscheck                     # rr tsc in each package with a tscheck script
+pnpm --filter @rrlab/cli test    # one package's tests
+```
+
+`pnpm test:unit` and `pnpm test:integration` run one kind of test. Unit tests live in `src/**/__tests__/`, and integration tests in `test/integration/`.
+
+In the repo, `pnpm rr` and `pnpm vland`, or `rr` and `vland` with mise, run each CLI from its `src/`, so an edit shows up without a build.
+
+## CI
+
+- **On each pull request to `main`:** CI runs `pnpm install --frozen-lockfile`, `pnpm rr check`, `pnpm test` and `pnpm build`, once on the Node floor in `mise.floor.toml` and once on the version in `mise.toml`. The required `Test` check passes when both do. Workflow audit runs [zizmor](https://docs.zizmor.sh) on every workflow in the repo, including those the vland templates generate.
+- **Git hooks** ([lefthook](https://lefthook.dev), in `lefthook/turborepo.yml`): on commit, `rr jscheck --fix-staged` on the staged files and, when TypeScript changed, `tscheck` on the changed packages and their dependents; on push, the tests of the affected packages.
+- **Every Monday:** `pnpm audit` on the lockfile, which keeps an issue labeled `dependency-audit` open while it finds known vulnerabilities (Dependency audit).
+
+## Preview releases
+
+A pull request from a `feat/*` or `fix/*` branch, or with the `preview` label, publishes each package it changes, and the packages that depend on them, to npm under the `pr-<number>` tag, once the tests pass. `vland-bot` comments the published versions on the pull request. To try a preview, install the package with that tag:
+
+```sh
+pnpm add -D @rrlab/cli@pr-123
+```
+
+For a `@rrlab/*-plugin` package, `rr plugins add` takes the same `@<tag>` suffix and passes it on to the plugin's `@rrlab/*-config` sibling, falling back to `latest` for a sibling the preview didn't publish:
+
+```sh
+rr plugins add biome@pr-123
+```
+
+## Generated files
+
+`run-run/cli/CLI.md` and `vland/cli/CLI.md` are generated, so don't edit them by hand. The cli docs workflow builds each CLI, which writes `dist/cli.usage.kdl`, and runs `usage generate markdown` on it. To see the result locally:
+
+```sh
+pnpm --filter ./run-run/cli build
+usage generate markdown --file run-run/cli/dist/cli.usage.kdl --out-file run-run/cli/CLI.md --replace-pre-with-code-fences
+```
diff --git a/run-run/astro-plugin/LICENSE b/run-run/astro-plugin/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 rcrd <ricardo@variable.land>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/run-run/astro-plugin/README.md b/run-run/astro-plugin/README.md
@@ -1,24 +1,26 @@
-# @rrlab/astro-plugin
+# astro-plugin
 
-Astro plugin for [`@rrlab/cli`](https://npmjs.com/package/@rrlab/cli). Provides the `typecheck` capability backed by [`astro check`](https://docs.astro.build/en/reference/cli-reference/#astro-check), so `rr tsc` and `rr check` type-check `.astro` files along with the rest of the project.
+`@rrlab/astro-plugin` is a [run-run](https://github.com/withvariablelab/dx/tree/main/run-run/cli) plugin for [`astro check`](https://docs.astro.build/en/reference/cli-reference/#astro-check). It gives `rr` the `typecheck` capability, so `rr tsc` and `rr check` type-check `.astro` files along with the rest of the project.
 
 ## Install
 
 ```sh
 rr plugins add astro
 ```
 
-`rr plugins add` installs `@rrlab/astro-plugin` and adds `@astrojs/check` and `typescript` as `devDependencies`: `astro check` needs both. It scaffolds no config: your Astro project already has its `tsconfig.json`, and `astro` itself stays your project's own dependency.
+`rr plugins add` installs `@rrlab/astro-plugin` and adds `@astrojs/check` and `typescript` as dev dependencies: `astro check` needs both. It writes no config file: your Astro project already has its `tsconfig.json`, and `astro` stays your project's own dependency.
+
+It needs `@rrlab/cli`, Astro 5 or later, `@astrojs/check` 0.9 or later, and TypeScript 5 or 6.
 
 ## What it provides
 
-| Capability | Surface |
-|---|---|
+| Capability | Commands |
+| --- | --- |
 | `typecheck` | `rr tsc` (workspace-aware in monorepos), `rr check`, `rr tsc doctor` |
 
-`rr tsc` runs `astro check` in each package with a `tsconfig.json`. It reports the same diagnostics as `astro check`, for `.astro` files and plain `.ts` files alike, and fails when `astro check` exits non-zero (any error, by default).
+`rr tsc` runs `astro check` in each package with a `tsconfig.json`. It reports the same diagnostics as `astro check`, for `.astro` files and plain `.ts` files alike, and fails when `astro check` exits non-zero, which it does on any error by default.
 
-`astro check` also checks your `.ts` files, so in an Astro project it replaces `ts`. Configure one `typecheck` provider. If another plugin also provides one (`ts`, or `oxc`), narrow it, e.g. `oxc({ only: ["lint", "format"] })`.
+`astro check` also checks your `.ts` files, so in an Astro project it replaces `ts`. Configure one `typecheck` provider. If another plugin also provides one, such as `ts` or `oxc`, narrow it: `oxc({ only: ["lint", "format"] })`.
 
 If `@astrojs/check` or `typescript` is missing, `rr tsc` fails and names it. Left alone, `astro check` would prompt to install them instead of checking anything.
 
@@ -28,4 +30,12 @@ If `@astrojs/check` or `typescript` is missing, `rr tsc` fails and names it. Lef
 rr plugins remove astro
 ```
 
-Removes `@astrojs/check` and `typescript` from `package.json` and drops the `astro()` entry from `run-run.config.{ts,mts}`. `astro` and your `tsconfig.json` are left untouched.
+It removes `@astrojs/check` and `typescript` from `package.json`, and drops `astro()` from `run-run.config.{ts,mts}`. It leaves `astro` and your `tsconfig.json` alone.
+
+## License
+
+[MIT](https://github.com/withvariablelab/dx/blob/main/LICENSE).
+
+<p align="center">
+  <a href="https://lab.variable.land"><img src="https://cdn.jsdelivr.net/gh/withvariablelab/brand@v0.3.1/.github/readme/logo.svg" width="24" alt="" align="absmiddle">&nbsp;Variable Land</a>
+</p>
diff --git a/run-run/biome-config/LICENSE b/run-run/biome-config/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 rcrd <ricardo@variable.land>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.