wheems 0.0.1 → 0.0.3

package/CHANGELOG.md

@@ -3,6 +3,74 @@
 Wheems follows [semantic versioning](https://semver.org). While it's 0.0.x, any release may
 change anything, including commands and config formats, without a migration path.
 
+## 0.0.3
+
+A new look for the cloud in the terminal, and clearer help when a Slack token is wrong. Still an
+early preview: not ready for real use. The first release published from GitHub.
+
+**Changed**
+
+- The cloud on the welcome screen and in `wheems setup` is now the mascot's outline, with its eye
+  and smile, instead of a solid shape whose face got lost. It's drawn in the terminal's text colour
+  (white on a dark terminal, near-black on a light one) rather than blue. It's left out when the
+  output isn't a terminal (piped or saved to a file) and when the terminal is narrower than 53
+  columns, so only the name, tagline and status are shown.
+- The cloud winks once when it appears, in an interactive terminal. Set `WHEEMS_NO_ANIMATION` to
+  stop it; it never winks in CI, in a dumb terminal, or when the output isn't a terminal.
+
+**Fixed**
+
+- When a pasted Slack token isn't right, setup says why instead of only "The bot token starts with
+  xoxb-": the app-level token pasted for the bot token (or the other way round), a user or refresh
+  token, two pastes run together, something in front of the token, or a space in it, each with
+  where in Slack to find the right one. It names tokens only by their standard prefix.
+
+## 0.0.2
+
+Fixes from the first preview, a welcome screen, and checks that catch common set-up problems.
+Still an early preview: not ready for real use.
+
+**Added**
+
+- `wheems` on its own shows a welcome screen: the cloud from the brand kit, in blue, beside the
+  name and "Your crew, ready for work.", then how the install is doing (workspaces and agents,
+  the service, search, and anything waiting for review). `wheems setup` opens with the cloud too.
+- `wheems init` creates the install when there isn't one, so setup can be scripted from a fresh
+  machine (connecting Slack still needs `wheems setup`).
+- `wheems doctor` checks that Claude Code is signed in (`claude auth status`), and that the app is
+  a member of each workspace's chat channel: Slack lists public channels the app isn't in, and
+  sends no messages from them. The service warns about such a channel when it starts.
+
+**Fixed**
+
+- Search needs SQLite full-text search (FTS5), which Node only bundles from 22.16 in the 22
+  line and from 24; no Node 23 release has it. `engines` is now `^22.16.0 || >=24`, the CLI and
+  `wheems service install` refuse other versions with a plain message, `wheems doctor` checks
+  that this Node's SQLite has full-text search, and search says so instead of failing with
+  "no such module: fts5".
+- `npm run build` now marks `dist/cli/main.js` executable, so a `wheems` linked with `npm link`
+  runs instead of failing with "Permission denied".
+- Slack messages with a file attached were silently ignored. Now a file with no words gets a reply
+  asking for the text, and with words the agent gets them and a note that files can't be passed
+  on yet.
+- After a quick reply from an agent, Wheems could add a false "The agent finished without
+  replying here": it recorded when a message was sent only after typing it in.
+- After connecting Slack, setup says to restart the service (which reads tokens only when it
+  starts) and how to let someone else talk to the agents.
+- On Linux, `wheems doctor` warns that the service needs macOS for now instead of passing.
+- Docs: where to install Herdr core ([herdr.dev/core](https://herdr.dev/core/)), npm as the way
+  to install, inviting the app to a channel, session names, which commands take `--home`, a
+  broken table in config.md, and milestone numbers in code comments.
+
+**Known issues**
+
+- Only one Slack connection, named `slack`, can be set up from `wheems setup` and `wheems init`;
+  a second Slack app has to be added by hand.
+- The Slack app's manifest asks for interactivity, which nothing uses until approvals with
+  buttons (milestone 3).
+- The launchd label is fixed, so only one install per Mac user can run as a service.
+- `wheems kb search --json` reports inbox notes as `kind: note`; the path tells them apart.
+
 ## 0.0.1
 
 The first preview: milestones 0 to 2 of the [roadmap](docs/roadmap.md). Not ready for real use.

package/README.md

@@ -78,9 +78,11 @@ Wheems was formerly called Opinr.
 
 You need:
 
-- macOS (the service runs under launchd; Linux comes later)
-- Node.js 22.13 or later
-- Herdr core 0.1.20 or later (`hc`)
+- macOS (the service runs under launchd; Linux, with systemd, comes with the always-on
+  milestone)
+- Node.js 22.16 or later in the 22 line, or 24 or later (not 23: its SQLite has no full-text
+  search, which Wheems needs)
+- Herdr core 0.1.20 or later (`hc`): see [herdr.dev/core](https://herdr.dev/core/) to install it
 - A Slack workspace where you can add apps
 
 Install the `wheems` command from npm:
@@ -102,9 +104,10 @@ npm link            # puts the wheems command on your PATH
 Clone it anywhere except `~/wheems`. That folder is your install: your private config, notes
 and knowledge base, kept in a git folder of its own that is never pushed anywhere.
 
-If your default `node` is older than 22.13, use a newer one, such as Homebrew's
+If your default `node` isn't one of those (Homebrew's `node` may be 23), use one that is, such as Homebrew's
 (`brew install node@22`), and run `/opt/homebrew/opt/node@22/bin/node dist/cli/main.js` in place
-of `wheems`. `wheems doctor` says which Node.js it runs on and fails when it's too old.
+of `wheems`. `wheems doctor` says which Node.js it runs on, and fails when it's unsupported or its SQLite has no
+full-text search.
 
 ## Set up
 
@@ -141,6 +144,14 @@ One Slack app serves every workspace, so you do this once.
 5. Give your Slack member ID (your profile, **⋯**, **Copy member ID**). Only people on this list
    can talk to your agents. Messages from anyone else are ignored.
 
+### Inviting the app to a channel
+
+A workspace that chats in a channel needs the app in that channel: in the channel, type
+`/invite` and choose the app. Slack lists public channels the app isn't in, so a channel name
+that's spelt right can still hear nothing; the service warns at start-up and `wheems doctor`
+checks it. The service looks channels up when it starts, so after creating a channel or renaming
+one, run `wheems service restart`.
+
 ### Trusting the workspace folder
 
 Claude Code and Codex ask once whether to trust a new folder, and nobody can answer that from
@@ -149,7 +160,9 @@ folder, then press Ctrl+C twice to come back. `wheems doctor` checks the trust.
 
 ### Without the menu
 
-Each part has a command of its own, for scripts:
+Each part has a command of its own, for scripts. `wheems init` creates the install too when
+there isn't one, so a fresh machine can start there; connecting Slack still needs `wheems setup`,
+because you type its tokens in yourself:
 
 ```bash
 wheems init personal                                   # a workspace on Claude Code
@@ -226,8 +239,9 @@ can be given skills, but nothing starts them yet: teams of agents come in later
 Message the Slack app (or the workspace's channel). Each message you send starts a
 **conversation**, and replies in its thread carry it on.
 
-- Each conversation is its own engine session in Herdr, named after the workspace and agent.
-  Watch it or take over with `hc attach <session>`.
+- Each conversation is its own engine session in Herdr, named after the workspace with a short
+  id for the thread, such as `personal-3f9a2c1b`. Watch it or take over with
+  `hc attach <session>`.
 - A 👀 reaction means your message has reached the agent. It goes when the agent answers.
 - The agent's last message of each turn is posted to the thread as its answer. The answer is
   read from the engine's own record of the conversation, never from the screen.
@@ -506,13 +520,15 @@ from its workspace's skills. Pinned skill versions must exist in the library.
 
 ## Command reference
 
-Every command takes `--home <dir>` for the install folder (default: `$WHEEMS_HOME`, then
-`~/wheems`).
+Commands that use the install take `--home <dir>` for the install folder (default:
+`$WHEEMS_HOME`, then `~/wheems`). `wheems service restart`, `service uninstall` and
+`slack manifest` don't need it.
 
 **For you**
 
 | Command                                                                        | What it does                                                                                              |
 | ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------- |
+| `wheems`                                                                       | The welcome screen: the cloud, and how the install is doing (workspaces, the service, search, review)     |
 | `wheems setup`                                                                 | The setup menu: engines, Slack, workspaces, knowledge, the service, doctor                                |
 | `wheems init <workspace> [--name] [--channel] [--engine] [--model]`            | Creates a workspace with its chief of staff. `--engine` is `claude-code` (default), `codex` or `opencode` |
 | `wheems doctor [--quick] [--json]`                                             | Checks the machine, Herdr core and the install                                                            |
@@ -649,6 +665,7 @@ skills:
 | `WHEEMS_SECRETS`      | The secrets file (default `~/.config/wheems/secrets.json`, or under `$XDG_CONFIG_HOME`) |
 | `WHEEMS_WORKSPACE`    | The workspace `wheems kb search` searches. Wheems sets it in every agent session        |
 | `WHEEMS_CONVERSATION` | The conversation an agent's commands belong to. Wheems sets it in every agent session   |
+| `WHEEMS_NO_ANIMATION` | Set to anything to stop the cloud winking on the welcome screen and in `wheems setup`   |
 
 ### Config the schemas accept but nothing uses yet
 
@@ -782,6 +799,23 @@ also run it against a fake `hc`, which is what CI uses. Set `WHEEMS_TEST_OLLAMA_
 | `examples/install/` | A complete example install                                                       |
 | `docs/`             | Design documents                                                                 |
 
+### Releasing
+
+GitHub publishes each release. To release, merge a pull request to `main` that:
+
+1. changes `version` in `package.json` (and `package-lock.json`);
+2. adds a `## <version>` section to `CHANGELOG.md`.
+
+The [release workflow](.github/workflows/release.yml) then runs the full check on Linux and
+macOS and publishes to npm. It then tags the commit `v<version>` and creates a GitHub release
+with that changelog section as its notes. A push to `main` whose version is already published and
+tagged does nothing.
+
+npm trusts the workflow through
+[trusted publishing](https://docs.npmjs.com/trusted-publishers), so no npm token is stored
+anywhere. The package's settings on npmjs.com name this repository and `release.yml` as its
+trusted publisher.
+
 ## More documentation
 
 The documents in [`docs/`](docs/) go deeper, and some describe the design of milestones not built

package/dist/cli/commands/service.js

@@ -1,12 +1,11 @@
 import { realpathSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
-import { NODE_MINIMUM_VERSION } from '../../doctor/doctor.js';
+import { nodeVersionProblem } from '../../util/node-support.js';
 import { defaultHome, paths } from '../../home.js';
 import { request } from '../../service/control.js';
 import { installService, plistPath, restartService, serviceStatus, uninstallService, } from '../../service/launchd.js';
 import { runService } from '../../service/service.js';
-import { isAtLeast } from '../../util/version.js';
 import { packageVersion } from '../version.js';
 /** The script that is running this CLI, resolved through npm links. */
 export function cliPath() {
@@ -14,9 +13,9 @@ export function cliPath() {
 }
 /** Installs the service under launchd with this Node.js and build, and waits for it to answer. */
 export async function installAndWait(where) {
-    if (!isAtLeast(process.versions.node, NODE_MINIMUM_VERSION)) {
-        throw new Error(`The service needs Node.js ${NODE_MINIMUM_VERSION} or later, and this is ${process.versions.node}.`);
-    }
+    const problem = nodeVersionProblem(process.versions.node);
+    if (problem !== null)
+        throw new Error(problem);
     const cli = cliPath();
     if (!cli.endsWith('.js')) {
         throw new Error('Install the service from a build of Wheems (npm run build), not from source.');

package/dist/cli/commands/setup.js

@@ -156,6 +156,10 @@ async function channels(options, where) {
     doc.setIn(['connections', connection, 'allowed_users'], doc.createNode(result.allowedUsers, { flow: true }));
     await writeFile(where.install, doc.toString());
     ui.success(`${entry.label} is connected. Its tokens are saved privately in ${where.secrets}`);
+    ui.info([
+        'The service reads tokens when it starts: restart it (Service) for these to take effect.',
+        `To let someone else talk to your agents, add their member ID to allowed_users under connections.${connection} in install.yaml, then restart the service.`,
+    ].join('\n'));
     return true;
 }
 /**

package/dist/cli/main.js

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
-// Check the Node.js version before loading anything that needs a newer one, so an old
-// Node.js gets a plain message rather than a stack trace from a dependency.
-const [major = 0, minor = 0] = process.versions.node.split('.').map(Number);
-if (major < 22 || (major === 22 && minor < 13)) {
-    process.stderr.write(`Wheems needs Node.js 22.13 or later, and this is ${process.versions.node} (${process.execPath}).\n`);
+// Check the Node.js version before loading anything that needs a newer one, so an
+// unsupported Node.js gets a plain message rather than a stack trace from a dependency.
+import { nodeVersionProblem } from '../util/node-support.js';
+const problem = nodeVersionProblem(process.versions.node);
+if (problem !== null) {
+    process.stderr.write(`${problem}\nThis is ${process.execPath}.\n`);
     process.exit(1);
 }
 const { defaultIo, run } = await import('./program.js');
@@ -13,7 +14,7 @@ process.exitCode = await run(process.argv.slice(2), {
     err: (text) => process.stderr.write(text),
     env: process.env,
     color,
+    columns: process.stdout.isTTY ? process.stdout.columns : undefined,
     ...defaultIo(),
 });
-export {};
 //# sourceMappingURL=main.js.map

package/dist/cli/program.d.ts

@@ -8,6 +8,8 @@ export interface Io {
     err: (text: string) => void;
     env: NodeJS.ProcessEnv;
     color: boolean;
+    /** The terminal's width, or undefined when the output isn't a terminal. */
+    columns?: number | undefined;
     registry: () => DriverRegistry;
     stdin: () => Promise<string>;
 }
@@ -15,6 +17,6 @@ export interface Io {
 export declare function defaultIo(): Pick<Io, 'registry' | 'stdin'>;
 /** Builds the `wheems` command. */
 export declare function createProgram(io: Io): Command;
-/** Runs the CLI and returns the exit code. */
+/** Runs the CLI and returns the exit code. With no command, it shows the welcome screen. */
 export declare function run(argv: string[], io: Io): Promise<number>;
 export declare function formatReport(report: DoctorReport, color: boolean): string;

package/dist/cli/program.js

@@ -15,8 +15,9 @@ import { registerSkill } from './commands/skill.js';
 import { registerNote } from './commands/note.js';
 import { registerReply } from './commands/reply.js';
 import { registerService } from './commands/service.js';
-import { setup } from './commands/setup.js';
+import { ensureInstall, setup } from './commands/setup.js';
 import { clackUi } from './clack-ui.js';
+import { canWink, renderWelcomeHead, renderWelcomeTail, SHOW_CURSOR, showCloud, welcomeStatus, wink, } from './welcome.js';
 import { installAndWait, serviceAnswers } from './commands/service.js';
 import { runCommand, runInteractive } from '../util/process.js';
 import { SetupCancelled } from '../contracts/setup.js';
@@ -88,7 +89,7 @@ export function createProgram(io) {
     });
     program
         .command('setup')
-        .description('Set up Wheems: connect channels, create workspaces, run the service')
+        .description('Set up Wheems: engines, chat channels, workspaces, search and the service')
         .option('--home <dir>', 'the install folder (default: $WHEEMS_HOME or ~/wheems)')
         .action(async (options) => {
         if (!process.stdin.isTTY || !process.stdout.isTTY) {
@@ -98,6 +99,13 @@ export function createProgram(io) {
         const where = paths(home, io.env);
         const registry = io.registry();
         const ui = clackUi();
+        io.out(renderWelcomeHead({
+            version: packageVersion(),
+            color: io.color,
+            cloud: showCloud(io.columns),
+        }));
+        if (canWink(io.columns, io.env))
+            await winkOnce(io);
         ui.intro(' Wheems setup ');
         try {
             await setup({
@@ -133,7 +141,7 @@ export function createProgram(io) {
     });
     program
         .command('init')
-        .description('Create a workspace with its chief of staff')
+        .description('Create a workspace with its chief of staff (and the install, if there is none)')
         .argument('<workspace>', 'the workspace id, such as personal')
         .option('--name <name>', 'its display name (default: from the id)')
         .option('--channel <channel>', "chat in this channel instead of the bot's direct messages")
@@ -154,8 +162,13 @@ export function createProgram(io) {
             throw new Error(`No engine "${options.engine}". Choose one of: ${known}`);
         }
         const setup = entry.engine;
+        const home = resolve(options.home ?? defaultHome(io.env));
+        // On a fresh machine, init makes the install too, so setup can be scripted.
+        const createdInstall = await ensureInstall(paths(home, io.env));
+        if (createdInstall)
+            io.out(`Created the install at ${home} (a git folder)\n`);
         const dir = await initWorkspace({
-            home: resolve(options.home ?? defaultHome(io.env)),
+            home,
             id,
             env: io.env,
             engine: {
@@ -206,8 +219,45 @@ export function createProgram(io) {
 function shellPath(path) {
     return /^[\w./-]+$/.test(path) ? path : `'${path.replaceAll("'", `'\\''`)}'`;
 }
-/** Runs the CLI and returns the exit code. */
+/**
+ * The cloud winks once. Ctrl+C meanwhile still gives the terminal its cursor back before
+ * stopping, as it would have done without the wink.
+ */
+async function winkOnce(io) {
+    const interrupted = () => {
+        io.out(SHOW_CURSOR);
+        process.exit(130);
+    };
+    process.once('SIGINT', interrupted);
+    try {
+        await wink({ version: packageVersion(), color: io.color, write: io.out });
+    }
+    finally {
+        process.off('SIGINT', interrupted);
+    }
+}
+/** Runs the CLI and returns the exit code. With no command, it shows the welcome screen. */
 export async function run(argv, io) {
+    if (argv.length === 0) {
+        const home = resolve(defaultHome(io.env));
+        // The welcome never fails: a problem reading the install becomes one of its lines.
+        // The status is read while the cloud is drawn and winks.
+        const reading = welcomeStatus(home, io.env).catch((error) => [
+            {
+                mark: '!',
+                text: `Couldn't read the install at ${home}: ${error instanceof Error ? error.message : String(error)}. Run wheems doctor.`,
+            },
+        ]);
+        io.out(renderWelcomeHead({
+            version: packageVersion(),
+            color: io.color,
+            cloud: showCloud(io.columns),
+        }));
+        if (canWink(io.columns, io.env))
+            await winkOnce(io);
+        io.out(renderWelcomeTail({ status: await reading, color: io.color }));
+        return 0;
+    }
     const program = createProgram(io);
     try {
         await program.parseAsync(argv, { from: 'user' });

package/dist/cli/welcome.d.ts

@@ -0,0 +1,68 @@
+/**
+ * The cloud: the mascot's outline (the brand kit's mascot.svg), traced in Unicode half blocks,
+ * with its eye and smile placed by hand so they read at this size. Half blocks are in every
+ * monospace font and most terminals draw them as exact rectangles, so it looks the same
+ * everywhere; an outline also reads on light and dark backgrounds alike. It has no colour of
+ * its own: it's drawn in the terminal's text colour, like the brand's ink app icon, so it's white
+ * on a dark terminal and near-black on a light one.
+ */
+export declare const CLOUD: string[];
+/** The brand line under the name. */
+export declare const TAGLINE = "Your crew, ready for work.";
+/** The columns the cloud and the words beside it need. */
+export declare const WELCOME_WIDTH: number;
+/**
+ * Whether to draw the cloud: only in a terminal wide enough for it and the words beside it.
+ * Piped into a file or another program, or read out by a screen reader, it would only be
+ * noise. `columns` is undefined when the output isn't a terminal.
+ */
+export declare function showCloud(columns: number | undefined): boolean;
+export interface WelcomeStatus {
+    mark: '✓' | '!' | '-';
+    text: string;
+}
+interface WelcomeOptions {
+    version: string;
+    status: WelcomeStatus[];
+    color: boolean;
+    /** Ends with the commands to try next. On by default. */
+    hints?: boolean;
+    /** Draws the cloud. On by default; see showCloud for when to leave it out. */
+    cloud?: boolean;
+}
+/** The welcome screen: the cloud with the name and tagline beside it, then the install's status. */
+export declare function renderWelcome(options: WelcomeOptions): string;
+/** The top of the welcome screen: the cloud and the words beside it, or just the words. */
+export declare function renderWelcomeHead(options: Omit<WelcomeOptions, 'status'>): string;
+/** The rest of the welcome screen: the install's status and the commands to try. */
+export declare function renderWelcomeTail(options: Omit<WelcomeOptions, 'version' | 'cloud'>): string;
+/**
+ * Whether the cloud may wink: only when it's drawn, so in a wide enough terminal, and not in
+ * CI, a dumb terminal, or for someone who has set WHEEMS_NO_ANIMATION.
+ */
+export declare function canWink(columns: number | undefined, env: NodeJS.ProcessEnv): boolean;
+/** How long the eye stays open before the wink, and how long it stays shut. */
+export declare const WINK_TIMING: {
+    readonly before: 400;
+    readonly shut: 150;
+};
+/**
+ * The cloud winks once: run straight after renderWelcomeHead is written, with the cursor on the
+ * line under the cloud. It redraws only the eye's row, hides the cursor meanwhile and always
+ * shows it again.
+ */
+export declare function wink(options: {
+    version: string;
+    color: boolean;
+    write: (text: string) => void;
+    sleep?: (ms: number) => Promise<void>;
+}): Promise<void>;
+export declare const HIDE_CURSOR = "\u001B[?25l";
+export declare const SHOW_CURSOR = "\u001B[?25h";
+/**
+ * What the welcome screen says about this install: its workspaces and agents, the service,
+ * search, and anything waiting for review. Quick: it reads files and pings the service, and
+ * never starts a session.
+ */
+export declare function welcomeStatus(home: string, env: NodeJS.ProcessEnv, ping?: (socket: string) => Promise<boolean>): Promise<WelcomeStatus[]>;
+export {};

package/dist/cli/welcome.js

@@ -0,0 +1,163 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { loadInstall } from '../config/load.js';
+import { paths } from '../home.js';
+import { listAboutYou } from '../review/review.js';
+import { request } from '../service/control.js';
+import { listProposals } from '../skills/proposals.js';
+/**
+ * The cloud: the mascot's outline (the brand kit's mascot.svg), traced in Unicode half blocks,
+ * with its eye and smile placed by hand so they read at this size. Half blocks are in every
+ * monospace font and most terminals draw them as exact rectangles, so it looks the same
+ * everywhere; an outline also reads on light and dark backgrounds alike. It has no colour of
+ * its own: it's drawn in the terminal's text colour, like the brand's ink app icon, so it's white
+ * on a dark terminal and near-black on a light one.
+ */
+// Every character is one UTF-16 unit, so .length is the width in columns.
+export const CLOUD = [
+    '           ▄█████▄▄',
+    '         ▄█▀     ▀▀█▄',
+    '    ▄█████▀        ▀█▄',
+    '   ██               ██',
+    '  ▄██               █▀',
+    ' ██▀  ██           ▀█▄▄',
+    '██                   ▀█▄',
+    '██   ▀▄▄▀             ██',
+    ' ██▄                 ▄█▀',
+    '  ▀▀█████████████████▀',
+];
+/** The brand line under the name. */
+export const TAGLINE = 'Your crew, ready for work.';
+const CLOUD_WIDTH = Math.max(...CLOUD.map((line) => line.length));
+/** The columns the cloud and the words beside it need. */
+export const WELCOME_WIDTH = CLOUD_WIDTH + 3 + TAGLINE.length;
+/**
+ * Whether to draw the cloud: only in a terminal wide enough for it and the words beside it.
+ * Piped into a file or another program, or read out by a screen reader, it would only be
+ * noise. `columns` is undefined when the output isn't a terminal.
+ */
+export function showCloud(columns) {
+    return columns !== undefined && columns >= WELCOME_WIDTH;
+}
+const BOLD = '\x1b[1m';
+const DIM = '\x1b[2m';
+const RESET = '\x1b[0m';
+/** The welcome screen: the cloud with the name and tagline beside it, then the install's status. */
+export function renderWelcome(options) {
+    return renderWelcomeHead(options) + renderWelcomeTail(options);
+}
+/** The row of the cloud with the eye in it, and the eye's columns. */
+const EYE = { row: 5, from: 6, to: 8 };
+function cloudRow(options, row, line) {
+    const paint = (code, text) => (options.color ? `${code}${text}${RESET}` : text);
+    const beside = {
+        4: paint(BOLD, 'wheems') + ' ' + paint(DIM, options.version),
+        5: TAGLINE,
+    };
+    const text = beside[row];
+    return text === undefined ? line : `${line.padEnd(CLOUD_WIDTH)}   ${text}`;
+}
+/** The top of the welcome screen: the cloud and the words beside it, or just the words. */
+export function renderWelcomeHead(options) {
+    const paint = (code, text) => (options.color ? `${code}${text}${RESET}` : text);
+    const lines = options.cloud === false
+        ? [paint(BOLD, 'wheems') + ' ' + paint(DIM, options.version), TAGLINE]
+        : CLOUD.map((line, row) => cloudRow(options, row, line));
+    return ['', ...lines].join('\n') + '\n';
+}
+/** The rest of the welcome screen: the install's status and the commands to try. */
+export function renderWelcomeTail(options) {
+    const paint = (code, text) => (options.color ? `${code}${text}${RESET}` : text);
+    const marks = { '✓': '\x1b[32m', '!': '\x1b[33m', '-': DIM };
+    return [
+        '',
+        ...options.status.map((s) => `${paint(marks[s.mark], s.mark)} ${s.text}`),
+        ...(options.status.length > 0 ? [''] : []),
+        ...(options.hints === false
+            ? []
+            : [paint(DIM, 'wheems setup · wheems doctor · wheems --help'), '']),
+    ].join('\n');
+}
+/**
+ * Whether the cloud may wink: only when it's drawn, so in a wide enough terminal, and not in
+ * CI, a dumb terminal, or for someone who has set WHEEMS_NO_ANIMATION.
+ */
+export function canWink(columns, env) {
+    return (showCloud(columns) &&
+        env.TERM !== 'dumb' &&
+        (env.CI ?? '') === '' &&
+        (env.WHEEMS_NO_ANIMATION ?? '') === '');
+}
+/** How long the eye stays open before the wink, and how long it stays shut. */
+export const WINK_TIMING = { before: 400, shut: 150 };
+/**
+ * The cloud winks once: run straight after renderWelcomeHead is written, with the cursor on the
+ * line under the cloud. It redraws only the eye's row, hides the cursor meanwhile and always
+ * shows it again.
+ */
+export async function wink(options) {
+    const sleep = options.sleep ?? ((ms) => new Promise((done) => setTimeout(done, ms)));
+    const up = CLOUD.length - EYE.row;
+    const open = CLOUD[EYE.row] ?? '';
+    const shut = open.slice(0, EYE.from) + '▄▄' + open.slice(EYE.to);
+    // Up to the eye's row, clear it, draw it again, and back down to where the cursor was.
+    const redraw = (line) => {
+        options.write(`\x1b[${String(up)}A\r\x1b[2K${cloudRow(options, EYE.row, line)}\x1b[${String(up)}B\r`);
+    };
+    options.write(HIDE_CURSOR);
+    try {
+        await sleep(WINK_TIMING.before);
+        redraw(shut);
+        await sleep(WINK_TIMING.shut);
+        redraw(open);
+    }
+    finally {
+        options.write(SHOW_CURSOR);
+    }
+}
+export const HIDE_CURSOR = '\x1b[?25l';
+export const SHOW_CURSOR = '\x1b[?25h';
+/**
+ * What the welcome screen says about this install: its workspaces and agents, the service,
+ * search, and anything waiting for review. Quick: it reads files and pings the service, and
+ * never starts a session.
+ */
+export async function welcomeStatus(home, env, ping = (socket) => request(socket, { op: 'ping' }, 1000).then((answer) => answer.ok, () => false)) {
+    const where = paths(home, env);
+    const hasInstall = await readFile(join(home, 'install.yaml')).then(() => true, () => false);
+    if (!hasInstall) {
+        return [{ mark: '!', text: `No install at ${tilde(home, env)} yet: run wheems setup` }];
+    }
+    const install = await loadInstall(home);
+    const workspaces = install.workspaces.filter((w) => w.config);
+    const agents = workspaces.reduce((n, w) => n + w.agents.length, 0);
+    const status = [];
+    status.push(workspaces.length > 0
+        ? {
+            mark: '✓',
+            text: `${count(workspaces.length, 'workspace')}, ${count(agents, 'agent')} in ${tilde(home, env)}`,
+        }
+        : { mark: '!', text: 'No workspaces yet: run wheems setup' });
+    status.push((await ping(where.socket))
+        ? { mark: '✓', text: 'The service is running' }
+        : { mark: '!', text: "The service isn't running: wheems service install" });
+    const embeddings = install.config?.knowledge.embeddings;
+    status.push(embeddings
+        ? { mark: '✓', text: `Search by meaning with ${embeddings.model ?? embeddings.driver}` }
+        : { mark: '-', text: 'Search by keyword only (wheems setup → Knowledge for meaning)' });
+    const waiting = (await listProposals(where.state)).length + (await listAboutYou(where.state)).length;
+    if (waiting > 0) {
+        status.push({ mark: '!', text: `${count(waiting, 'thing')} waiting for you: wheems review` });
+    }
+    return status;
+}
+function count(n, noun) {
+    return `${String(n)} ${noun}${n === 1 ? '' : 's'}`;
+}
+function tilde(path, env) {
+    const home = env.HOME;
+    return home !== undefined && home !== '' && path.startsWith(`${home}/`)
+        ? `~${path.slice(home.length)}`
+        : path;
+}
+//# sourceMappingURL=welcome.js.map

package/dist/contracts/channel.d.ts

@@ -1,7 +1,7 @@
 import type { Driver, HealthCheck } from './driver.js';
 /**
  * The channel contract: sends and receives messages, buttons and threads.
- * Version one ships Slack (milestone 1) and Telegram and email (milestone 9).
+ * Version one ships Slack (milestone 1) and Telegram and email (milestone 10).
  *
  * A channel driver holds one connection, such as one Slack app. Channels inside
  * it are addressed by the driver's own channel id.
@@ -27,6 +27,16 @@ export interface ChannelDriver extends Driver<'channel'> {
     react(message: MessageRef, reaction: string, on: boolean): Promise<void>;
     /** Disconnects. No handler calls happen after it resolves. Safe to call twice. */
     stop(): Promise<void>;
+    /**
+     * Optional: a channel's id from its name (or its id), or null when the app can't see it.
+     * Drivers without it take channel names as ids.
+     */
+    resolveChannel?(nameOrId: string): Promise<string | null>;
+    /**
+     * Optional: whether the app is a member of a channel, so messages there reach it. Null when it
+     * can't tell. Seeing a channel isn't enough: Slack lists public channels the app isn't in.
+     */
+    isMember?(channelId: string): Promise<boolean | null>;
 }
 export interface MessageRef {
     channel: string;
@@ -56,6 +66,10 @@ export interface InboundMessage {
     /** True for a direct message between the person and the bot. */
     direct: boolean;
     receivedAt: Date;
+    /** Files attached to it, by name. Wheems can't pass their contents on yet. */
+    files?: {
+        name: string;
+    }[];
 }
 export interface ButtonPress {
     type: 'button';