@mercury-fw/cli 0.42.0 → 0.44.0

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # @mercury-fw/cli
 
+## 0.44.0
+
+### Minor Changes
+
+- 2c63bbf: One person across accounts: linking them by a code.
+
+  - `POST /link` on the HTTP surface hands the caller a one-time code (`xxxx-xxxx-xxxx`, ten minutes, single use). They send it from the other account, on any channel, twice. The first time Mercury says whom the account would be linked to, the second time it links it.
+  - From then on the account is the person it's linked to: one private area, one memory, the same roles. Its earlier area stays where it was, and undoing the link gives it back.
+  - A link never touches the terminal, never chains, and is refused for an account the directory already knows as someone else.
+  - The links live on the vault's volume, out of the vault's git and out of reach of the model and the HTTP reads.
+  - `mfw identity links | link | unlink` lets the operator manage them, for instances where nobody can be shown a code.
+  - Channels get the code through the confirmation hook they already call (`ctx.confirm`), and the HTTP surface gets `ctx.linking`.
+  - Fixed: `ctx.confirm` refused someone the core doesn't admit before checking that their text was a token at all. On Google Chat, every message from an unknown sender came back as the refusal.
+
+### Patch Changes
+
+- Updated dependencies [2c63bbf]
+  - @mercury-fw/core@0.44.0
+  - @mercury-fw/utils@0.44.0
+
+## 0.43.0
+
+### Minor Changes
+
+- 07eb858: ZITADEL as the user directory.
+
+  - `@mercury-fw/plugin-zitadel` exports `zitadelDirectory`. Someone calling with a ZITADEL token is the ZITADEL user the token names, with the role keys of their active role assignments on the project `ZITADEL_PROJECT_ID`. A user ZITADEL doesn't find, or one that isn't active, is unknown. It reads through the zitadel CLI's service user, from code.
+  - `mfw create --directory <id>` (`static` or `zitadel`) gives the new app a user directory, and the wizard asks for one.
+
+### Patch Changes
+
+- @mercury-fw/core@0.43.0
+- @mercury-fw/utils@0.43.0
+
 ## 0.42.0
 
 ### Patch Changes

package/README.md

@@ -16,6 +16,7 @@
   - [`mfw vault <command>`](#mfw-vault-command)
   - [`mfw memory list`](#mfw-memory-list)
   - [`mfw memory read <collection> [--limit N]`](#mfw-memory-read-collection---limit-n)
+  - [`mfw identity links`, `link`, `unlink`](#mfw-identity-links-link-unlink)
   - [`mfw reset <memory|wiki>`](#mfw-reset-memorywiki)
   - [`mfw credentials setup <plugin>`](#mfw-credentials-setup-plugin)
   - [`mfw credentials check <plugin>`](#mfw-credentials-check-plugin)
@@ -62,6 +63,7 @@ Then it runs `bun install` in the app and creates a git repository on `main` wit
 | `--channels <ids>` | Comma-separated: `google-chat`, `http`. |
 | `--plugins <ids>` | Comma-separated: `jira`, `bitbucket`, `atlassian-admin`, `zitadel`. |
 | `--auth <id>` | The HTTP channel's auth provider, `oidc` or `static`: required with `http`, refused without it, since the channel doesn't start without one. The wizard asks for it once `http` is chosen. |
+| `--directory <id>` | The user directory, `static` or `zitadel`: who the people are and their roles. Without one, the person is whoever the channel says, with no roles. |
 | `--local-packages <folder>` | Installs the packages packed in `<folder>` (`bun pm pack`) instead of the registry's, as [`mfw local-packages`](#mfw-local-packages-folder--mfw-local-packages---off) does on an existing app: their versions come from the tarballs, so a package that isn't published yet works too, and no newer `mfw` is looked up on the registry. For trying unreleased packages in a new app; the test bed makes its apps this way. |
 | `--git-remote <url>` | The repository's `origin`, taken as typed. |
 | `--no-install` | Don't run `bun install`. |
@@ -173,6 +175,16 @@ mfw memory read episodic_memory
 mfw memory read semantic_facts --limit 5
 ```
 
+### `mfw identity links`, `link`, `unlink`
+
+The links that make several accounts one person: one private area, one memory, the same roles. People link their own accounts with a code (the HTTP surface's `POST /link` gives one, they send it from the other account, twice); these are for the operator, in a one-off container, where nobody can be shown a code. Identities are written `<provider>:<id>`, as the channel or the auth provider vouches for them (`google-chat:users/123`, `oidc:3123`, `static:alice`). The running service applies a change within five minutes. Undoing a link gives the account back its own area, untouched.
+
+```bash
+mfw identity links
+mfw identity link google-chat:users/123 oidc:3123
+mfw identity unlink google-chat:users/123
+```
+
 ### `mfw reset <memory|wiki>`
 
 Deletes for good what the assistant remembers: `memory` is every collection on Qdrant, `wiki` the whole vault. It reads the volume's real name from the compose file, tells you which one is about to go, and asks you to type the app's name (the `name` in `package.json`); anything else, an empty answer, a `y` or closing the input included, deletes nothing and exits 1. Once confirmed it stops the service using the volume, removes its container and the volume, and starts the service again on an empty one (`docker compose stop`, `rm -f`, `docker volume rm`, `up -d`). After `memory`, a running app is restarted too (`docker compose restart mercury`), since it sets up its collections only when it starts.

package/dist/src/app/commands.d.ts

@@ -21,6 +21,7 @@ export type AppDeps = {
  * bin whose file isn't there yet. The core moves in lockstep with this CLI. */
 export declare const VAULT_CLI = "node_modules/@mercury-fw/core/src/wiki/vault-cli.ts";
 export declare const MEMORY_CLI = "node_modules/@mercury-fw/core/src/memory/memory-cli.ts";
+export declare const IDENTITY_CLI = "node_modules/@mercury-fw/core/src/identity/links-cli.ts";
 /** What `mfw reset` can wipe: the compose service using the volume, the
  * volume's key in the compose file, and how to say what's lost. */
 export declare const RESET_TARGETS: {
@@ -52,6 +53,8 @@ export declare function appCommands(app: App, deps: AppDeps): {
     vault: (args: string[]) => Promise<number>;
     /** `args` is the memory CLI's own command line (`list`, `read <collection>`, …). */
     memory: (args: string[]) => Promise<number>;
+    /** `args` is the account links CLI's own command line (`links`, `link <identity> <owner>`, `unlink <identity>`). */
+    identity: (args: string[]) => Promise<number>;
     /** Deletes `target`'s volume once the user types the app's name, then
      * brings its service back up on an empty volume. The volume's real name
      * comes from the compose file, and a wrong answer deletes nothing. */

package/dist/src/args.d.ts

@@ -16,6 +16,8 @@ export type CreateArgs = {
     plugins?: string[];
     /** The auth provider, which goes with the HTTP channel. */
     auth?: string;
+    /** The user directory. */
+    directory?: string;
     /** The repository's origin, taken as typed. */
     gitRemote?: string;
     /** A folder of packed tarballs the app installs instead of the registry's packages. */
@@ -34,6 +36,7 @@ export type CreateOptions = {
     channels?: string;
     plugins?: string;
     auth?: string;
+    directory?: string;
     gitRemote?: string;
     localPackages?: string;
     yes?: boolean;

package/dist/src/catalog.d.ts

@@ -1,5 +1,5 @@
 /**
- * The channels, auth providers and tool plugins `mfw create` can put in a new app. Written
+ * The channels, auth providers, tool plugins and user directories `mfw create` can put in a new app. Written
  * by hand for now: once the packages are published, each plugin will describe
  * itself (kind, export, env vars) and this list goes away. `catalog.test.ts`
  * checks every entry against the real package until then.
@@ -11,13 +11,14 @@ export type EnvVar = {
     comment: string;
     value?: string;
 };
-/** A channel, auth provider or tool plugin the app can include. `id` is the
- * plugin's own `name` (what the logs and `dependsOn` call it), `exportName` the
- * value the app's config imports from `package`. An auth provider goes with the
- * HTTP channel, which doesn't start without one. */
+/** A channel, auth provider, tool plugin or user directory the app can include.
+ * `id` is the plugin's own `name` (what the logs and `dependsOn` call it; for a
+ * directory, the choice's name), `exportName` the value the app's config
+ * imports from `package`. An auth provider goes with the HTTP channel, which
+ * doesn't start without one; a directory goes with any channel. */
 export type CatalogEntry = {
     id: string;
-    kind: "channel" | "auth" | "tool";
+    kind: "channel" | "auth" | "tool" | "directory";
     package: string;
     exportName: string;
     env: EnvVar[];

package/dist/src/render.d.ts

@@ -8,6 +8,8 @@ export type RenderInput = {
     plugins: string[];
     /** The HTTP channel's auth provider: required with it, refused without it. */
     auth?: string;
+    /** The user directory: who the people are and their roles. */
+    directory?: string;
     versions: Record<string, string>;
 };
 /** Builds every file of the new app. Throws on an invalid app name, an empty
@@ -17,10 +19,10 @@ export declare function renderApp(input: RenderInput): Map<string, string>;
 /** Why `name` can't be an app name, or undefined when it can. Shared with the
  * wizard, which checks the name as it's typed. */
 export declare function appNameError(name: string): string | undefined;
-/** Names the first channel, plugin or auth provider id the catalog doesn't
- * have, with the valid ones, or undefined when all are known. Shared with the
- * command, which checks the flags before asking anything. */
-export declare function selectionError(channels: string[], plugins: string[], auth?: string): string | undefined;
+/** Names the first channel, plugin, auth provider or directory id the catalog
+ * doesn't have, with the valid ones, or undefined when all are known. Shared
+ * with the command, which checks the flags before asking anything. */
+export declare function selectionError(channels: string[], plugins: string[], auth?: string, directory?: string): string | undefined;
 /** What's wrong with pairing the HTTP channel and the auth provider: it
  * doesn't start without one, and one without it has nothing to authenticate.
  * Undefined when they go together. Shared with the command, which checks it

package/dist/src/wizard.d.ts

@@ -9,6 +9,8 @@ export type Answers = {
     plugins: string[];
     /** The HTTP channel's auth provider, there exactly when that channel is. */
     auth?: string;
+    /** The user directory, when there's one. */
+    directory?: string;
     gitRemote?: string;
 };
 export declare const DEFAULT_ASSISTANT_NAME = "Mercury";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mercury-fw/cli",
-  "version": "0.42.0",
+  "version": "0.44.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -41,20 +41,21 @@
   "comment:shape": "The Mercury CLI (`mfw`). `mfw create <dir>` writes a new Mercury app from the template. The framework packages move in lockstep with it, so a new app gets them at the CLI's own version; plugins and channels at the registry's latest. The plugin and channel packages are devDependencies only for the catalog test. `main(argv)` is exported for create-mercury-agent.",
   "dependencies": {
     "@clack/prompts": "^1.8.1",
-    "@mercury-fw/core": "0.42.0",
-    "@mercury-fw/utils": "0.42.0",
+    "@mercury-fw/core": "0.44.0",
+    "@mercury-fw/utils": "0.44.0",
     "commander": "^15.0.0"
   },
   "devDependencies": {
-    "@mercury-fw/channel-google-chat": "0.5.0",
-    "@mercury-fw/channel-http": "0.6.0",
     "@mercury-fw/auth-oidc": "0.1.0",
     "@mercury-fw/auth-static": "0.2.0",
-    "@mercury-fw/formatter": "0.42.0",
+    "@mercury-fw/channel-google-chat": "0.5.0",
+    "@mercury-fw/channel-http": "0.7.0",
+    "@mercury-fw/directory-static": "0.1.0",
+    "@mercury-fw/formatter": "0.44.0",
     "@mercury-fw/plugin-atlassian-admin": "0.3.1",
-    "@mercury-fw/plugin-bitbucket": "0.3.0",
-    "@mercury-fw/plugin-jira": "0.6.0",
-    "@mercury-fw/plugin-zitadel": "0.1.0",
+    "@mercury-fw/plugin-bitbucket": "0.3.1",
+    "@mercury-fw/plugin-jira": "0.6.1",
+    "@mercury-fw/plugin-zitadel": "0.2.0",
     "@mercury-fw/typescript-config": "*",
     "@types/bun": "^1.4.2",
     "typescript": "^6.0.3"

package/src/app/commands.ts

@@ -44,6 +44,7 @@ const SERVICE = "mercury";
  * bin whose file isn't there yet. The core moves in lockstep with this CLI. */
 export const VAULT_CLI = "node_modules/@mercury-fw/core/src/wiki/vault-cli.ts";
 export const MEMORY_CLI = "node_modules/@mercury-fw/core/src/memory/memory-cli.ts";
+export const IDENTITY_CLI = "node_modules/@mercury-fw/core/src/identity/links-cli.ts";
 
 /** What `mfw reset` can wipe: the compose service using the volume, the
  * volume's key in the compose file, and how to say what's lost. */
@@ -100,6 +101,8 @@ export function appCommands(app: App, deps: AppDeps) {
     vault: (args: string[]) => oneOff(["bun", VAULT_CLI, ...args]),
     /** `args` is the memory CLI's own command line (`list`, `read <collection>`, …). */
     memory: (args: string[]) => oneOff(["bun", MEMORY_CLI, ...args]),
+    /** `args` is the account links CLI's own command line (`links`, `link <identity> <owner>`, `unlink <identity>`). */
+    identity: (args: string[]) => oneOff(["bun", IDENTITY_CLI, ...args]),
     /** Deletes `target`'s volume once the user types the app's name, then
      * brings its service back up on an empty volume. The volume's real name
      * comes from the compose file, and a wrong answer deletes nothing. */

package/src/args.ts

@@ -17,6 +17,8 @@ export type CreateArgs = {
   plugins?: string[];
   /** The auth provider, which goes with the HTTP channel. */
   auth?: string;
+  /** The user directory. */
+  directory?: string;
   /** The repository's origin, taken as typed. */
   gitRemote?: string;
   /** A folder of packed tarballs the app installs instead of the registry's packages. */
@@ -36,6 +38,7 @@ export type CreateOptions = {
   channels?: string;
   plugins?: string;
   auth?: string;
+  directory?: string;
   gitRemote?: string;
   localPackages?: string;
   yes?: boolean;
@@ -59,6 +62,7 @@ export function toCreateArgs(folder: string, opts: CreateOptions): CreateArgs {
   if (opts.channels !== undefined) args.channels = list(opts.channels);
   if (opts.plugins !== undefined) args.plugins = list(opts.plugins);
   if (opts.auth !== undefined && opts.auth.trim() !== "") args.auth = opts.auth.trim();
+  if (opts.directory !== undefined && opts.directory.trim() !== "") args.directory = opts.directory.trim();
   if (opts.localPackages !== undefined) args.localPackages = opts.localPackages;
   // Blank is none, as in the wizard.
   if (opts.gitRemote !== undefined && opts.gitRemote.trim() !== "") args.gitRemote = opts.gitRemote.trim();

package/src/catalog.ts

@@ -1,5 +1,5 @@
 /**
- * The channels, auth providers and tool plugins `mfw create` can put in a new app. Written
+ * The channels, auth providers, tool plugins and user directories `mfw create` can put in a new app. Written
  * by hand for now: once the packages are published, each plugin will describe
  * itself (kind, export, env vars) and this list goes away. `catalog.test.ts`
  * checks every entry against the real package until then.
@@ -9,13 +9,14 @@
  * example: `value` is the example value, empty when the deployer must fill it. */
 export type EnvVar = { name: string; comment: string; value?: string };
 
-/** A channel, auth provider or tool plugin the app can include. `id` is the
- * plugin's own `name` (what the logs and `dependsOn` call it), `exportName` the
- * value the app's config imports from `package`. An auth provider goes with the
- * HTTP channel, which doesn't start without one. */
+/** A channel, auth provider, tool plugin or user directory the app can include.
+ * `id` is the plugin's own `name` (what the logs and `dependsOn` call it; for a
+ * directory, the choice's name), `exportName` the value the app's config
+ * imports from `package`. An auth provider goes with the HTTP channel, which
+ * doesn't start without one; a directory goes with any channel. */
 export type CatalogEntry = {
   id: string;
-  kind: "channel" | "auth" | "tool";
+  kind: "channel" | "auth" | "tool" | "directory";
   package: string;
   exportName: string;
   env: EnvVar[];
@@ -122,6 +123,28 @@ export const CATALOG: CatalogEntry[] = [
     exportName: "zitadelPlugin",
     env: [],
   },
+  {
+    id: "static",
+    kind: "directory",
+    package: "@mercury-fw/directory-static",
+    exportName: "staticDirectory",
+    env: [
+      {
+        name: "DIRECTORY_STATIC_PEOPLE",
+        comment:
+          'Required: the people, as JSON: [{"id": "alice", "roles": ["mercury.act-as-self"], "identities": ["static:alice"]}]',
+      },
+    ],
+  },
+  {
+    id: "zitadel",
+    kind: "directory",
+    package: "@mercury-fw/plugin-zitadel",
+    exportName: "zitadelDirectory",
+    env: [{ name: "ZITADEL_PROJECT_ID", comment: "Required: the ZITADEL project whose roles count" }],
+    // It calls the zitadel CLI, which the package downloads as it installs.
+    trusts: ["@mercury-fw/plugin-zitadel"],
+  },
 ];
 
 /** The catalog entry of `kind` with `id`, or undefined when there is none. */

package/src/main.ts

@@ -29,6 +29,7 @@ function answersFromFlags(args: CreateArgs, defaultName: string): Answers {
     channels: args.channels ?? [],
     plugins: args.plugins ?? [],
     ...(args.auth !== undefined ? { auth: args.auth } : {}),
+    ...(args.directory !== undefined ? { directory: args.directory } : {}),
     ...(args.gitRemote !== undefined ? { gitRemote: args.gitRemote } : {}),
   };
 }
@@ -127,7 +128,7 @@ async function create(args: CreateArgs, rawArgs: string[], relaunch: Relaunch, g
   const pairedByFlags = args.yes || (args.channels !== undefined && args.auth !== undefined);
   const early =
     targetError(dir) ??
-    selectionError(args.channels ?? [], args.plugins ?? [], args.auth) ??
+    selectionError(args.channels ?? [], args.plugins ?? [], args.auth, args.directory) ??
     (pairedByFlags ? pairingError(args.channels ?? [], args.auth) : undefined) ??
     remoteError(args);
   if (early !== undefined) {
@@ -138,9 +139,17 @@ async function create(args: CreateArgs, rawArgs: string[], relaunch: Relaunch, g
   if (answers === undefined) {
     return 1;
   }
-  const chosen = CATALOG.filter((e) =>
-    e.kind === "auth" ? e.id === answers.auth : (e.kind === "channel" ? answers.channels : answers.plugins).includes(e.id),
-  ).map((e) => e.package);
+  const chosen = [
+    ...new Set(
+      CATALOG.filter((e) =>
+        e.kind === "auth"
+          ? e.id === answers.auth
+          : e.kind === "directory"
+            ? e.id === answers.directory
+            : (e.kind === "channel" ? answers.channels : answers.plugins).includes(e.id),
+      ).map((e) => e.package),
+    ),
+  ];
   const versions = await appVersions(chosen, {
     registry: registryFrom(process.env.MFW_REGISTRY),
     ...(packs !== undefined ? { local: Object.fromEntries(packs.map((p) => [p.name, p.version])) } : {}),
@@ -162,7 +171,7 @@ async function create(args: CreateArgs, rawArgs: string[], relaunch: Relaunch, g
       ...(answers.gitRemote !== undefined ? { remote: answers.gitRemote } : {}),
       commitMessage: [
         `Scaffold with mfw create ${cliVersion()}`,
-        `Channels: ${none(answers.channels)}\nPlugins: ${none(answers.plugins)}${answers.auth !== undefined ? `\nAuth: ${answers.auth}` : ""}`,
+        `Channels: ${none(answers.channels)}\nPlugins: ${none(answers.plugins)}${answers.auth !== undefined ? `\nAuth: ${answers.auth}` : ""}${answers.directory !== undefined ? `\nDirectory: ${answers.directory}` : ""}`,
       ],
     },
     run,

package/src/program.ts

@@ -67,6 +67,10 @@ function buildProgram(handlers: ProgramHandlers, result: { code: number }): Comm
       "--auth <id>",
       `the HTTP channel's auth provider, required with it: ${CATALOG.filter((e) => e.kind === "auth").map((e) => e.id).join(", ")}`,
     )
+    .option(
+      "--directory <id>",
+      `the user directory, who the people are and their roles: ${CATALOG.filter((e) => e.kind === "directory").map((e) => e.id).join(", ")} (default: none)`,
+    )
     .option("--git-remote <url>", "the repository's origin, taken as typed (default: none)")
     .option(
       "--local-packages <folder>",
@@ -214,6 +218,35 @@ Examples:
       inApp((app) => app.memory(["read", collection, ...(opts.limit === undefined ? [] : ["--limit", opts.limit])]))(),
     );
 
+  const identity = program
+    .command("identity")
+    .summary("the accounts linked to a person")
+    .description(
+      "Lists, makes and undoes the links that make several accounts one person (one private area, the same roles), in a one-off container. People link their own accounts with a code; this is for the operator, where nobody can be shown one.",
+    )
+    .helpCommand(false)
+    .addHelpText("after", INSIDE_AN_APP);
+  identity
+    .command("links")
+    .summary("the linked accounts")
+    .description("Lists every linked account and the account it belongs to.")
+    .action(async () => inApp((app) => app.identity(["links"]))());
+  identity
+    .command("link")
+    .summary("links an account to another")
+    .description(
+      "Makes <identity> the same person as <owner>, both as <provider>:<id> (e.g. google-chat:users/123, oidc:3123). The running service applies it within five minutes.",
+    )
+    .argument("<identity>", "the account to link")
+    .argument("<owner>", "the account it belongs to")
+    .action(async (account: string, owner: string) => inApp((app) => app.identity(["link", account, owner]))());
+  identity
+    .command("unlink")
+    .summary("undoes an account's link")
+    .description("Makes <identity> a person of its own again; what it had before being linked is still there.")
+    .argument("<identity>", "as mfw identity links prints it")
+    .action(async (account: string) => inApp((app) => app.identity(["unlink", account]))());
+
   program
     .command("reset")
     .summary("deletes memory or the wiki, after confirmation")

package/src/render.ts

@@ -28,6 +28,8 @@ export type RenderInput = {
   plugins: string[];
   /** The HTTP channel's auth provider: required with it, refused without it. */
   auth?: string;
+  /** The user directory: who the people are and their roles. */
+  directory?: string;
   versions: Record<string, string>;
 };
 
@@ -66,18 +68,19 @@ export function renderApp(input: RenderInput): Map<string, string> {
   const channels = selected("channel", input.channels);
   const tools = selected("tool", input.plugins);
   const auth = selected("auth", input.auth === undefined ? [] : [input.auth])[0];
+  const directory = selected("directory", input.directory === undefined ? [] : [input.directory])[0];
   const assistantName = input.assistantName.trim();
 
   return new Map([
     [".dockerignore", dockerignore],
-    [".env.example", renderEnv(channels, auth, tools)],
+    [".env.example", renderEnv(channels, auth, tools, directory)],
     [".gitignore", gitignore],
     ["Dockerfile", dockerfile],
-    ["README.md", renderReadme(input.name, channels, auth, tools)],
+    ["README.md", renderReadme(input.name, channels, auth, tools, directory)],
     ["docker-compose.yml", renderCompose(input.name, channels.some((c) => c.id === "http"))],
     ["markdown.d.ts", markdownDts],
-    ["mercury.config.ts", renderConfig(channels, auth, tools)],
-    ["package.json", renderPackageJson(input.name, channels, auth, tools, input.versions)],
+    ["mercury.config.ts", renderConfig(channels, auth, tools, directory)],
+    ["package.json", renderPackageJson(input.name, channels, auth, tools, input.versions, directory)],
     ["persona/identity.md", `You are ${assistantName}, ${input.role.trim().replace(/\.+$/, "")}.\n`],
     // A replacer function, not a string: in a replacement string "$&" and the
     // like are patterns, and the name must land verbatim.
@@ -112,7 +115,8 @@ function validate(input: RenderInput): void {
   if (/[\r\n]/.test(input.assistantName) || /[\r\n]/.test(input.role)) {
     throw new Error("The assistant name and role must each be one line");
   }
-  const selection = selectionError(input.channels, input.plugins, input.auth) ?? pairingError(input.channels, input.auth);
+  const selection =
+    selectionError(input.channels, input.plugins, input.auth, input.directory) ?? pairingError(input.channels, input.auth);
   if (selection !== undefined) {
     throw new Error(selection);
   }
@@ -121,14 +125,15 @@ function validate(input: RenderInput): void {
 /** The ids of the catalog entries of `kind`. */
 const idsOf = (kind: CatalogEntry["kind"]): string[] => CATALOG.filter((e) => e.kind === kind).map((e) => e.id);
 
-/** Names the first channel, plugin or auth provider id the catalog doesn't
- * have, with the valid ones, or undefined when all are known. Shared with the
- * command, which checks the flags before asking anything. */
-export function selectionError(channels: string[], plugins: string[], auth?: string): string | undefined {
+/** Names the first channel, plugin, auth provider or directory id the catalog
+ * doesn't have, with the valid ones, or undefined when all are known. Shared
+ * with the command, which checks the flags before asking anything. */
+export function selectionError(channels: string[], plugins: string[], auth?: string, directory?: string): string | undefined {
   for (const [kind, ids, label] of [
     ["channel", channels, "channel"],
     ["tool", plugins, "plugin"],
     ["auth", auth === undefined ? [] : [auth], "auth provider"],
+    ["directory", directory === undefined ? [] : [directory], "directory"],
   ] as const) {
     const valid = idsOf(kind);
     const unknown = ids.find((id) => !valid.includes(id));
@@ -158,7 +163,12 @@ function selected(kind: CatalogEntry["kind"], ids: string[]): CatalogEntry[] {
 /** `mercury.config.ts`: imports, the formatter helpers of the plugins that have
  * any, then the config with each plugin (wrapped in the formatter when it has
  * starting rules) and channel. */
-function renderConfig(channels: CatalogEntry[], auth: CatalogEntry | undefined, tools: CatalogEntry[]): string {
+function renderConfig(
+  channels: CatalogEntry[],
+  auth: CatalogEntry | undefined,
+  tools: CatalogEntry[],
+  directory: CatalogEntry | undefined,
+): string {
   const withRules = tools.filter((t) => t.formatter);
   const imports = ['import { defineMercuryConfig } from "@mercury-fw/core";'];
   if (withRules.length > 0) {
@@ -168,7 +178,7 @@ function renderConfig(channels: CatalogEntry[], auth: CatalogEntry | undefined,
     const names = t.formatter ? `${t.exportName}, type ${t.formatter.displaysType}` : t.exportName;
     imports.push(`import { ${names} } from "${t.package}";`);
   }
-  for (const c of [...channels, ...(auth ? [auth] : [])]) {
+  for (const c of [...channels, ...(auth ? [auth] : []), ...(directory ? [directory] : [])]) {
     imports.push(`import { ${c.exportName} } from "${c.package}";`);
   }
   imports.push('import identity from "./persona/identity.md" with { type: "text" };');
@@ -191,6 +201,7 @@ function renderConfig(channels: CatalogEntry[], auth: CatalogEntry | undefined,
     plugins,
     channelList,
     ...(auth ? [`  auth: ${auth.exportName},`] : []),
+    ...(directory ? [`  directory: ${directory.exportName},`] : []),
     "});",
     "",
   ].join("\n");
@@ -213,15 +224,17 @@ function renderPluginEntry(t: CatalogEntry): string {
 
 /** `package.json`: the core, the formatter when a plugin is wrapped in it, the
  * chosen packages, and every tool plugin trusted to run its postinstall (it
- * downloads the plugin's CLI). */
+ * downloads the plugin's CLI), plus what a chosen entry says it needs trusted. */
 function renderPackageJson(
   name: string,
   channels: CatalogEntry[],
   auth: CatalogEntry | undefined,
   tools: CatalogEntry[],
   versions: Record<string, string>,
+  directory: CatalogEntry | undefined,
 ): string {
-  const packages = ["@mercury-fw/core", ...[...channels, ...(auth ? [auth] : []), ...tools].map((e) => e.package)];
+  const chosen = [...channels, ...(auth ? [auth] : []), ...tools, ...(directory ? [directory] : [])];
+  const packages = [...new Set(["@mercury-fw/core", ...chosen.map((e) => e.package)])];
   if (tools.some((t) => t.formatter)) {
     packages.push("@mercury-fw/formatter");
   }
@@ -248,7 +261,7 @@ function renderPackageJson(
     // hands the app's commands over to it.
     devDependencies: { "@mercury-fw/cli": `^${cli}`, "@types/bun": "^1.4.2", typescript: "^6.0.3" },
   };
-  const trusted = [...new Set([...tools.map((t) => t.package), ...[...channels, ...tools].flatMap((e) => e.trusts ?? [])])];
+  const trusted = [...new Set([...tools.map((t) => t.package), ...chosen.flatMap((e) => e.trusts ?? [])])];
   if (trusted.length > 0) {
     manifest.trustedDependencies = trusted.sort();
   }
@@ -257,12 +270,18 @@ function renderPackageJson(
 
 /** The env example: the core's variables, then a section per chosen entry
  * that reads any variable. */
-function renderEnv(channels: CatalogEntry[], auth: CatalogEntry | undefined, tools: CatalogEntry[]): string {
+function renderEnv(
+  channels: CatalogEntry[],
+  auth: CatalogEntry | undefined,
+  tools: CatalogEntry[],
+  directory: CatalogEntry | undefined,
+): string {
   const block = (vars: EnvVar[]) => vars.map((v) => `# ${v.comment}\n${v.name}=${v.value ?? ""}`).join("\n");
   const sections = [block(CORE_ENV)];
-  for (const entry of [...channels, ...(auth ? [auth] : []), ...tools]) {
+  for (const entry of [...channels, ...(auth ? [auth] : []), ...tools, ...(directory ? [directory] : [])]) {
     if (entry.env.length > 0) {
-      sections.push(`# --- ${entry.id}\n${block(entry.env)}`);
+      // A directory can share its id with a tool plugin of the same package.
+      sections.push(`# --- ${entry.id}${entry.kind === "directory" ? " directory" : ""}\n${block(entry.env)}`);
     }
   }
   return `${sections.join("\n\n")}\n`;
@@ -317,7 +336,13 @@ function renderCompose(name: string, hasHttp: boolean): string {
 }
 
 /** The app's README: what it was scaffolded with and how to run it. */
-function renderReadme(name: string, channels: CatalogEntry[], auth: CatalogEntry | undefined, tools: CatalogEntry[]): string {
+function renderReadme(
+  name: string,
+  channels: CatalogEntry[],
+  auth: CatalogEntry | undefined,
+  tools: CatalogEntry[],
+  directory: CatalogEntry | undefined,
+): string {
   const list = (entries: CatalogEntry[]) => (entries.length > 0 ? entries.map((e) => e.id).join(", ") : "none");
   return `# ${name}
 
@@ -325,7 +350,7 @@ A Mercury app, scaffolded by \`mfw create\`.
 
 - Channels: ${list(channels)}
 ${auth ? `- Auth: ${auth.id}\n` : ""}- Tool plugins: ${list(tools)}
-
+${directory ? `- Directory: ${directory.id}\n` : ""}
 ## Layout
 
 - \`mercury.config.ts\`: what the app is made of (tool plugins, channels, how their lists read) and the assistant's persona.

package/src/wizard.ts

@@ -19,6 +19,8 @@ export type Answers = {
   plugins: string[];
   /** The HTTP channel's auth provider, there exactly when that channel is. */
   auth?: string;
+  /** The user directory, when there's one. */
+  directory?: string;
   gitRemote?: string;
 };
 
@@ -87,6 +89,17 @@ export async function askAnswers(args: CreateArgs, dir: string): Promise<Answers
   }
   const plugins = await pick("tool", "Tool plugins (space to select)", args.plugins ?? []);
   if (plugins === undefined) return cancelled();
+  const NO_DIRECTORY = "";
+  const pickedDirectory = await p.select({
+    message: "User directory (who the people are and their roles; none: whoever the channel says, with no roles)",
+    options: [
+      { value: NO_DIRECTORY, label: "none" },
+      ...CATALOG.filter((e) => e.kind === "directory").map((e) => ({ value: e.id, label: e.id, hint: e.package })),
+    ],
+    initialValue: args.directory ?? NO_DIRECTORY,
+  });
+  if (p.isCancel(pickedDirectory)) return cancelled();
+  const directory = pickedDirectory === NO_DIRECTORY ? undefined : pickedDirectory;
   // Asked only when there will be a repository and the flag didn't say.
   let gitRemote = args.gitRemote;
   if (args.git && gitRemote === undefined) {
@@ -105,6 +118,7 @@ export async function askAnswers(args: CreateArgs, dir: string): Promise<Answers
       `Channels: ${channels.length > 0 ? channels.join(", ") : "none"}`,
       ...(auth !== undefined ? [`Auth: ${auth}`] : []),
       `Tool plugins: ${plugins.length > 0 ? plugins.join(", ") : "none"}`,
+      `Directory: ${directory ?? "none"}`,
       ...(args.git ? [`Origin: ${gitRemote ?? "none"}`] : []),
     ].join("\n"),
     "Summary",
@@ -118,6 +132,7 @@ export async function askAnswers(args: CreateArgs, dir: string): Promise<Answers
     channels,
     plugins,
     ...(auth !== undefined ? { auth } : {}),
+    ...(directory !== undefined ? { directory } : {}),
     ...(gitRemote !== undefined ? { gitRemote } : {}),
   };
 }