Skip to content

First Run

Mel edited this page Nov 10, 2026 · 1 revision

The app asks two questions before it shows the views:

open -> choose who -> choose project -> browse + installed

If no usable stack checkout is found, the setup screen comes first. See Install for provisioning; the lookup order is below.

Who

Lists the workers in the stack (its worker entries). Pick one.

who?

> 1 mel
  2 yuno

↑↓ enter
Key Does
↑ ↓ or j k move the cursor
Enter pick the row under the cursor
1–9 pick that row at once

If the stack lists no workers, the screen shows (._.) none and continue without one. If the list fails, it shows the error with retry and continue without one. Skipping lasts for this session only.

The user is only a label. The top bar shows it; the stack commands never receive it.

Project

project

browse folder

recent
> 1 /home/dev/projects/folio
  2 /home/dev/projects/sandbox

↑↓ enter

scan

‹ mel

(The /home/dev/... paths are fixtures from the docs, not real paths.)

Control Does
browse folder opens the system folder picker
recent rows open a project; same keys as who. Up to 10, newest first
scan lists the folders one level down in the scan roots (see below)
open (scan result) selects that folder as the project
Escape or ‹ <name> back to who

A path that does not exist or is not a folder is refused, and the message stays on this screen. The markers in scan results and in the project (stack.toml, .git, package.json and so on) are existence checks. The app reads and runs nothing inside the project.

Scan roots are the scanRoot and scanRoots settings if set. Otherwise they are the parent of the stack checkout plus ~/Projects, ~/dev and ~/code, when those exist. A scan result says has imports when the folder has a stack.toml, plain folder when it has no markers, and otherwise lists the markers it has.

Switching later

  • Click the user name in the top bar: back to who.
  • Click the project path in the top bar: back to project. The project is unset until you pick another one.

Stack checkout

When the stack cannot be used, the views are replaced by this screen:

no escacs/stack checkout found: looked upward from the app, its install
folder and the working folder for tools/stack/cli.mjs. Pick your stack clone
in settings (the folder containing tools/stack/cli.mjs).

pick stack folder   re-check

The app looks for the checkout in this order:

  1. The folder saved in settings (stackPath). Set by pick stack folder here, or change in installed.
  2. The ESCACS_STACK environment variable.
  3. A search upward from the app's executable, from the folder it was built in, and from the working folder, for tools/stack/cli.mjs. A normal install finds nothing this way.

pick stack folder takes the folder that contains tools/stack/cli.mjs. re-check runs the checks again. A saved folder wins over ESCACS_STACK.

A picked folder is checked before it is saved. An invalid pick is refused with the reason shown on this screen and is not remembered, so the app never blocks on a bad folder at the next launch. This screen has no auto button; auto in installed only appears once the app is usable.

Top bar and footer

browse / installed                        mel  …/projects/folio
  • browse and installed switch views. The current one is marked.
  • While an operation runs, its name and … appear before the user name.
  • (x_x) appears when node is not usable. Hover it for the message.
  • The user and project buttons go back to who and project (see above).

Footer, bottom of the window: the app version, then → <version> available when the startup check found a newer release, then N update or N updates when installed imports have changes waiting. The last two link to installed.

Any other route shows (o_O) not found.

See also: Install, Browse, Installed, Keyboard Shortcuts.

Clone this wiki locally