# Starting a project: the commands and the rule

These commands are on your `PATH` as `office`, `board`, `merge`, `review`, `triage` and
`project-reset`. Each is a two-line wrapper in `~/.local/bin` that runs the real script in this
repository — a wrapper, not a symlink, because a symlinked script resolves its own directory to
`~/.local/bin` and then cannot find its siblings. The previous project's wrappers were moved to
`~/.local/bin/.old-harness/`, not deleted.

Replaces the previous project's four commands. There are three now, and one rule that removes
most of the confusion.

## The rule

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

`--host` exists for exactly one case: the folder is on a different machine from the shell you are
typing in. It is stated once; after that the project file remembers it.

## The three commands

| What you want | Command |
|---|---|
| adopt a folder | `bin/office <folder> --project "<Paperclip project name>"` |
| adopt a folder Paperclip has never seen | `bin/office <folder> --new "<Name>"` |
| adopt a folder that lives on another machine | `bin/office <folder> --project "<Name>" --host nixos-desktop` |
| repair or rebuild the panes | `bin/board`, `bin/board --replace`, `bin/board --reset` |
| close everything and start again | `bin/project-reset <folder>` |

Nothing else is needed. In particular you do **not** create the session by hand any more: the
previous design needed `tuios new --host …` because `office` could not create a session. This one
can, through the daemon's own verb, so the second command is gone.

## What `bin/office` does, in order

1. Reads the folder. If another machine is named, checks first whether that name is *this*
   machine, and runs locally if it is. (The previous version once tried to `ssh` to itself.)
2. Resolves a host name to an address ssh can reach: `nixos-desktop`/`.13` → `192.168.20.13`,
   `sam-4screen-desktop`/`.27` → `192.168.20.27`, `sam-thinkpad`/`.51` → `192.168.20.51`.
3. If it really is another machine: tests the login with `ssh -o BatchMode=yes <address> true`,
   then runs the same command there, and prints how to attach.
4. On the machine that owns the folder: creates the Paperclip project if `--new` was given, or
   adopts the existing one; writes `.harness/harness.toml`, `check.sh`, `NOTES.md` — never
   overwriting anything that exists.
   Before the remote run it copies this folder's commands to the other machine at
   `~/.local/share/paperclip-harness/bin/` and leaves a short `~/.local/bin/office` there, so
   nothing has to be installed by hand. On `.27` and `.51` `~/.local/bin` is not on `PATH`
   yet, so there the command is called by its full path.
5. Creates the session if it is missing, on that machine's daemon.
6. Builds the eight panes, in order, each pane claimed by workspace **name**.

The last step it cannot do is show you the session. A program may not move your client: the
daemon refuses `switch-session` from a pane. Switch with TUIOS's own session switcher, or
`tuios attach --host <machine> <session>`.

## The three rebuild levels

| Command | What it does |
|---|---|
| `bin/board` | creates what is missing, closes nothing |
| `bin/board --replace` | closes this project's panes, then builds all eight again |
| `bin/board --reset` | closes **every** pane in the session, waits for none to remain, clears the workspace names, then builds |

`--reset` exists because `--replace` on a half-built session can run out of workspace slots and
leave pages missing.

Inside a pane, `R` in `Repair>repair` rebuilds everything; `B` only adds what is missing.

## Traps this design keeps from the previous one

- A pane's command must carry the project, or a rebuild shows the wrong one.
- Compare a host name against this machine's own names and addresses before ssh, or you log in to
  yourself.
- Never store a workspace number; TUIOS deletes an emptied workspace and renumbers the rest.
- A pane that never exits keeps a workspace alive. `Shell>shell` is that pane here.
- Scripts resolve their own directory with `realpath`, so a symlinked wrapper still finds its
  siblings.