feat(init): read the port and the pkg repo for --freebsd-port

README.md

@@ -277,11 +277,42 @@ $ dbuild info
 Scaffold a new dbuild project with starter files.
 
 ```sh
-dbuild init                     # config.yaml + Containerfile
+dbuild init                     # config.yaml, compose.yaml, Containerfile.j2, root/
 dbuild init --github            # + GitHub Actions workflow
 dbuild init --woodpecker        # + Woodpecker CI pipeline
 ```
 
+The image is a single process on `base-exec`: `/init` runs the setup script
+`root/daemonless/init.d/20-<name>` as root, then execs the launcher
+`root/daemonless/libexec/<name>` (the `CMD`) as `bsd`. Health is the base's
+`/healthz` against `HEALTHCHECK_URL`. The `Containerfile*.j2` keep the title,
+description, category, ports and volumes as placeholders: `dbuild generate`
+fills them from `compose.yaml`, which stays the one place to edit them. A
+pkg-only scaffold makes `pkg` the default tag with a `latest` alias.
+
+From a FreeBSD port, the port fills in what it knows:
+
+```sh
+dbuild init --freebsd-port net-p2p/transmission-components
+dbuild init --freebsd-port gitea --port 3000           # bare name: looked up in the tree, then pkg
+dbuild init --freebsd-port https://www.freshports.org/sysutils/backrest/
+dbuild init --freebsd-port net-p2p/qbittorrent --flavors nox   # one pkg tag per flavor
+```
+
+| From the port | Goes to |
+|---|---|
+| `COMMENT`, `WWW`, `LICENSE` (+`LICENSE_COMB`) as SPDX, category | compose.yaml, image labels |
+| rc script `command=`/`procname=` (through `/usr/sbin/daemon`), plist `bin/` entries | the launcher, with the rc flags and conf dirs as a comment |
+| rc `*_port` default or a `localhost:PORT` in pkg-message | `cit.port` and the compose `ports` (else 8080 and a warning) |
+| `FLAVORS` | listed; `--flavors a,b` scaffolds `pkg-a`, `pkg-b` |
+
+Defaults change with `--freebsd-port`: variants are `pkg,pkg-latest`, and from a
+directory of image repos the files land in `./<name>/` (override with `--dir`).
+Without a ports tree (`$PORTSDIR`, `/usr/ports`) the labels come from `pkg rquery`;
+the launcher then needs the binary set by hand. Every scaffold ends with the
+items left to review and the next commands (`dbuild logo`, `dbuild generate`,
+`dbuild build`, `dbuild test`).
+
 ## Global Options
 
 ```

dbuild/cli.py

@@ -327,7 +327,19 @@ def _make_parser() -> argparse.ArgumentParser:
     init_parser.add_argument(
         "--freebsd-port",
         metavar="PORT",
-        help="initialize from a FreeBSD port (e.g. net-p2p/bazarr)",
+        help=(
+            "scaffold from a FreeBSD port: category/name (net-p2p/transmission), "
+            "a bare port or package name, or a FreshPorts URL; reads the ports "
+            "tree ($PORTSDIR, /usr/ports), else the pkg repo"
+        ),
+    )
+    init_parser.add_argument(
+        "--dir",
+        metavar="DIR",
+        help=(
+            "directory to scaffold into, created if missing (default: the current "
+            "directory, or ./<name> when run from a workspace of image repos)"
+        ),
     )
     init_parser.add_argument(
         "--flavors",
@@ -363,14 +375,18 @@ def _make_parser() -> argparse.ArgumentParser:
     init_parser.add_argument(
         "--port",
         type=int,
-        default=8080,
-        help="default application port (default: 8080)",
+        help=(
+            "web/API port (default: the port's rc script or pkg-message "
+            "with --freebsd-port, else 8080)"
+        ),
     )
     init_parser.add_argument(
         "--variants",
         metavar="LIST",
-        default="latest",
-        help="comma-separated list of variants to scaffold (default: latest)",
+        help=(
+            "comma-separated list of variants to scaffold "
+            "(default: latest, or pkg,pkg-latest with --freebsd-port)"
+        ),
     )
     init_parser.add_argument(
         "--community",