Find a study wherever it is, and start on a port that is free

Three things the one-folder-per-study layout ran into.

**Discovery walks down.** A plain directory is now walked all the way, so
`fluksio sync dev` finds `dev/s1_baseline/study.py` and naming each study is
no longer the price of the layout. Hidden directories, `__pycache__`,
`node_modules` and virtualenvs are left alone, and a package is taken whole.

Two files that would import under one module name are refused, naming both:
Python keeps one module per name, so the second would silently *be* the first
— and a node's generated body imports by that name, so a worker would run the
wrong study's code. The message says the fix, which is an `__init__.py` per
study directory. A module that raises while importing is now a sentence
naming the file rather than an importlib traceback.

**`run` and `sweep` sync downwards too**, so the flow is found from the
repository root without the sync-then-`--no-sync` two-step. A study that will
not import is a warning rather than a stopped run, since a walk meets every
study and a half-finished one two directories away is not this run's problem.
The upload was already a no-op for a flow nothing changed in, so what the walk
costs is import time — `--sync PATH` narrows it, and skipping unchanged
subtrees would need a cache keyed on file state that is deliberately not here.

**`serve` moves off a busy default port** — 8001, 8002, up to twenty — says
which it took, and writes that one into `client.json`. A port given with
`--port` still fails when it is taken, because naming one is asking for it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01A9Hdrmf2cwNABCnE5x9UJa

docs/code/cli.md

@@ -39,11 +39,17 @@ On the first start it creates an admin account and prints its password **once**.
 Nothing else has to be running: no database server, no message broker, no
 Docker.
 
+The default port moves out of the way when something already has it — 8001,
+8002, and so on — and says which one it took; the URL written to
+`client.json` is the one it is actually on. A port you *asked* for is never
+moved off: `--port 9000` on a taken 9000 fails, because something else is
+there and you named it.
+
 | Option | Default | What it does |
 |---|---|---|
 | `--data-dir PATH` | `./.fluksio` (or `$FLUKSIO_HOME`) | where this installation keeps everything |
 | `--host HOST` | `127.0.0.1` | what to bind |
-| `--port PORT` | `8000` | what to listen on |
+| `--port PORT` | `8000`, or the next free one | what to listen on |
 | `--log-level LEVEL` | `info` | uvicorn's log level |
 | `--admin-email ADDR` | `admin@example.com` | the account created on first run |
 | `--admin-password PW` | generated | set it instead of having one generated |
@@ -152,6 +158,15 @@ each one with a generated import shim per node. A directory that is a package
 is walked; a dotted name is imported as it stands; nothing is loaded from a
 file path, because the shim has to import the same way.
 
+A plain directory is walked all the way down, so one folder per study —
+`fluksio sync dev` over `dev/s1_baseline/study.py` — needs no naming. Hidden
+directories, `__pycache__`, `node_modules` and virtualenvs are left alone. Two
+files that would import under the same name are refused rather than
+silently collapsed into one: Python keeps one module per name, and a node's
+generated body imports by that name, so `dev/s1/study.py` and `dev/s2/study.py`
+need an `__init__.py` each — making them `s1.study` and `s2.study` — or
+different filenames.
+
 | Flag | What it does |
 |---|---|
 | `--dry-run` | print the flow documents and shims, upload nothing |
@@ -182,9 +197,16 @@ upgraded its cache is keyed on the whole repository, as it was before. See
 fluksio run train --lr 0.05 --seed 7 [--wait]
 ```
 
-Syncs the working directory, then submits a run — so the command after an edit
-is this one and nothing else. Flags that are not its own are the flow's
-inputs, typed by what the flow declares them as. `--wait` blocks until the run
+Syncs the working directory *and everything under it*, then submits a run — so
+the command after an edit is this one and nothing else, from the repository
+root as readily as from the study's own folder. A study that will not import
+is a warning rather than a stopped run; the upload is already a no-op for a
+flow nothing changed in, so what the walk costs is importing the others.
+`--sync dev/s1_baseline` (repeatable) narrows it to what you name when that
+is not free, and `--no-sync` skips it entirely.
+
+Flags that are not its own are the flow's inputs, typed by what the flow
+declares them as. `--wait` blocks until the run
 finishes and exits non-zero if it failed. `--follow` waits as well, and prints
 the numbers the run reports as they arrive: