# The startup commands: how the system is opened, and why they look like this

The previous attempt produced four commands. They work. This explains what each does, the
decisions behind them, and the traps — so a new session does not redesign them from scratch.

## The four commands

```
office <folder>                     open a project on this machine
office <folder> --host nixos-desktop   open a project that lives on another machine
project-reset <folder>              start a project again from nothing
board                               create any missing screen in the current session
```

They live in `~/paseo/harness/bin` and are installed as small wrappers in `~/.local/bin`,
so they work from any directory. They are **wrappers, not symlinks**: a symlink made the
scripts think they lived in `~/.local/bin`, which broke every sibling command they call.

## What `office` decides, in order

1. **The folder.** Made absolute, `~` expanded, created if missing. Everything else hangs
   off this.
2. **The session name.** `--session` if given, otherwise the folder's own name. One project,
   one session. Not one session with many projects.
3. **Which machine.** In this order:
   - `--host NAME` if given;
   - otherwise the host remembered in `<folder>/.harness/host`;
   - otherwise this machine.
4. **Is that machine this one?** If the name resolves to this machine's hostname or one of
   its own addresses, it runs **locally** and says `host: nixos-desktop (this machine)`.
   This check exists because the first version tried to `ssh` to the machine it was already
   running on, which is refused, and looked like a login problem.
5. **If it really is another machine**, it tests the login first (`ssh -o BatchMode=yes
   <address> true`) and, only if that works, runs the same command there, then prints the
   attach lines for both a graphical and a terminal client.

Host names map to addresses that ssh can actually reach:

| Name you type | Address used |
|---|---|
| `nixos-desktop`, `.13` | `192.168.20.13` |
| `sam-4screen-desktop`, `.27` | `192.168.20.27` |
| `sam-thinkpad`, `.51` | `192.168.20.51` |

The first version mapped names to the literal strings `.13`, `.27`, `.51`, which ssh cannot
resolve. That is why `office` used to fail with "Could not resolve hostname .13".

**The host is only remembered when it is genuinely remote.** A local project never gets a
`.harness/host` file, because a stale "remote" entry is how a project starts rebuilding
itself on the wrong machine.

## The rule that matters for the person

> The session and the folder live on the same machine.
> If you are typing inside the session, on the machine that owns the folder, you type
> `office <folder>` and nothing else.

`--host` exists for one case only: the folder is on a different machine from the one your
shell is on. It is stated once, then remembered.

## Why `--host` is stated twice when starting from scratch

Because two separate things are being created, by two different tools:

1. `tuios new --host nixos-desktop cookie` — TUIOS creates the **session** on that machine.
2. `office ~/src/cookie --host nixos-desktop` — the harness prepares the **folder** there.

Neither tool can do the other's job. TUIOS cannot create a folder project; `office` cannot
create a session (measured: `tuios new` fails with "Standard output is not a terminal" when
run from anything but a real terminal). Once the folder has been prepared there, `office`
remembers the host and the second flag is never needed again.

## What happens after the host is settled

1. **Adopt the folder.** `new-project` writes only what is missing: the project settings,
   the role files, one page note per screen, a to-do list, the verify command, the plan
   stubs. It never overwrites a file that exists, so running it twice is safe.
2. **Check the session exists.** The session table is colour-coded, so names are matched
   after stripping escape sequences. A plain ` name ` match fails on a live session and
   made a running session look absent.
3. **Build the screens.** Pages are created in a fixed order, and each pane is claimed in a
   workspace **by name**, never by number. TUIOS deletes a workspace whose last pane closes
   and renumbers the rest, so a remembered number is always wrong eventually.
4. **Every page keeps one pane that never exits** (its notes pane). Without it, a page
   disappears when its work finishes, which is exactly what made the factory seem to
   restart.

## The three rebuild levels

```
board              create what is missing; close nothing
board --replace    rebuild every page, in order
board --reset      empty the session first, then rebuild     (~20 s for 26 panes)
```

`--reset` lists the panes, closes each by id, **waits until the session reports zero panes**,
clears every workspace name, then builds. It exists because `--replace` on a half-built
session ran out of workspace slots and left pages short.

In a running panel, `R` repairs every page (it runs `board`) and then restarts itself with
the code on disk. `q` exits and leaves the pane.

## Traps, in short

- A pane's own command must carry the project, or `board` rebuilds the wrong one.
- Compare host names against the machine's own addresses before ssh, or you will try to log
  in to yourself.
- Strip colour codes before matching anything TUIOS prints.
- Never store a workspace number.
- A page with no permanent pane will vanish.
- A repair that does not carry the project name silently does nothing.

## Relationship to the new project

The four screens in `docs/PLAN.md` replace most of what `office` builds today. What survives
and must be kept: the host resolution above, the "same machine for folder and session" rule,
the wrapper-not-symlink detail, resolve-by-name, and the permanent notes pane per page.