1 files changed, 131 insertions, 0 deletions
diff --git a/man/witryna.1 b/man/witryna.1
new file mode 100644
index 0000000..473d395
--- /dev/null
+++ b/man/witryna.1
@@ -0,0 +1,131 @@
+.TH witryna 1 2026-02-15 "witryna 0.2.0"
+.SH NAME
+witryna \- Minimalist Git\-based static site deployment orchestrator
+.SH SYNOPSIS
+\fBwitryna\fR <\fIcommand\fR> [\fB\-\-config\fR \fIFILE\fR] [\fIargs\fR]
+.SH DESCRIPTION
+Minimalist Git\-based static site deployment orchestrator.
+.PP
+Witryna listens for webhook HTTP requests, pulls the corresponding Git
+repository (with automatic Git LFS fetch and submodule initialization),
+runs a user\-defined build command inside an ephemeral container and
+publishes the resulting assets via atomic symlink switching.
+.PP
+A health\-check endpoint is available at GET /health (returns 200 OK).
+.PP
+Witryna does not serve files, terminate TLS, or manage DNS.
+It is designed to sit behind a reverse proxy (Nginx, Caddy, etc.).
+.SH "SUBCOMMANDS"
+.TP
+\fBserve\fR [\fB\-\-config\fR \fIFILE\fR]
+Start the deployment server (foreground).
+.TP
+\fBvalidate\fR [\fB\-\-config\fR \fIFILE\fR]
+Validate configuration file and print summary.
+.TP
+\fBrun\fR [\fB\-v\fR|\fB\-\-verbose\fR] [\fB\-\-config\fR \fIFILE\fR] \fIsite\fR
+Trigger a one\-off build for a site (synchronous, no server).
+Use \fB\-v\fR to stream full build output to stderr in real\-time.
+.TP
+\fBstatus\fR [\fB\-\-json\fR] [\fB\-\-config\fR \fIFILE\fR] [\fIsite\fR]
+Show deployment status for configured sites.
+If \fIsite\fR is given, show the last 10 deployments for that site.
+Use \fB\-\-json\fR for machine\-readable JSON output.
+A \fB+\fR marker indicates the active deployment (the build the \fBcurrent\fR symlink points to).
+.TP
+\fBswitch\fR [\fB\-\-config\fR \fIFILE\fR] \fIsite\fR \fIbuild\fR
+Switch the active build for a site. Atomically updates the \fBcurrent\fR symlink
+to point to the specified build timestamp. Use \fBwitryna status\fR \fIsite\fR to
+list available builds with their timestamps. Does not run post\-deploy hooks.
+.TP
+\fBcleanup\fR [\fB\-\-keep\fR \fIN\fR] [\fB\-\-config\fR \fIFILE\fR] [\fIsite\fR]
+Remove old builds and logs.
+If \fIsite\fR is given, clean only that site; otherwise clean all.
+\fB\-\-keep\fR \fIN\fR overrides the \fBmax_builds_to_keep\fR config value.
+.SH OPTIONS
+.TP
+\fB\-\-config\fR \fIFILE\fR
+Path to the configuration file (available on every subcommand).
+If not specified, searches: ./witryna.toml, $XDG_CONFIG_HOME/witryna/witryna.toml,
+/etc/witryna/witryna.toml.
+.TP
+\fB\-\-help\fR
+Print help information.
+.SH "SIGNALS"
+.TP
+\fBSIGHUP\fR
+Reload configuration from \fIwitryna.toml\fR without restarting the server.
+Sites can be added, removed, or modified on the fly.
+Changes to \fBlisten_address\fR, \fBbase_dir\fR, \fBlog_dir\fR,
+and \fBlog_level\fR are detected but require a full restart to take effect;
+a warning is logged when these fields differ.
+.TP
+\fBSIGTERM\fR, \fBSIGINT\fR
+Initiate graceful shutdown.
+In\-progress builds are allowed to finish before the process exits.
+.SH "EXIT STATUS"
+.TP
+\fB0\fR
+Clean shutdown after SIGTERM/SIGINT (\fBserve\fR), configuration valid (\fBvalidate\fR),
+build succeeded (\fBrun\fR), status displayed (\fBstatus\fR), or build switched (\fBswitch\fR).
+Post\-deploy hook failure is non\-fatal and still exits 0.
+Hooks run on both successful and failed builds.
+.TP
+\fB1\fR
+Startup failure, validation error, build failure, site not found, configuration error,
+or command\-line usage error (unknown flag, missing subcommand, etc.).
+.SH "INSTALLATION"
+When installed via deb or rpm packages, the post\-install script automatically
+detects the available container runtime and configures system\-level access:
+.TP
+\fBDocker\fR
+The \fBwitryna\fR user is added to the \fBdocker\fR group and a systemd
+override is installed at
+\fI/etc/systemd/system/witryna.service.d/10\-runtime.conf\fR
+granting access to the Docker socket.
+.TP
+\fBPodman\fR
+Subordinate UID/GID ranges are allocated (100000\-165535), user lingering is
+enabled, and a systemd override is installed that disables
+\fBRestrictNamespaces\fR and sets \fBXDG_RUNTIME_DIR\fR.
+.PP
+If neither runtime is found at install time, a warning is printed.
+Install a runtime and reinstall the package, or manually copy the appropriate
+override template from \fI/usr/share/doc/witryna/examples/systemd/\fR to
+\fI/etc/systemd/system/witryna.service.d/10\-runtime.conf\fR.
+.SH "FILES"
+.TP
+\fI/etc/witryna/witryna.toml\fR
+Conventional configuration path for system\-wide installs.
+The shipped systemd unit passes \fB\-\-config /etc/witryna/witryna.toml\fR
+explicitly; without \fB\-\-config\fR the CLI defaults to \fIwitryna.toml\fR
+in the current working directory.
+.TP
+\fI/var/lib/witryna/clones/<site>/\fR
+Git repository clones.
+.TP
+\fI/var/lib/witryna/builds/<site>/<timestamp>/\fR
+Timestamped build outputs.
+.TP
+\fI/var/lib/witryna/builds/<site>/current\fR
+Symlink to the latest successful build.
+.TP
+\fI/var/lib/witryna/builds/<site>/state.json\fR
+Current build state (building, success, failed, hook\ failed).
+Written atomically at each pipeline phase; read by \fBwitryna status\fR
+to show in\-progress builds with elapsed time.
+.TP
+\fI/var/lib/witryna/cache/<site>/\fR
+Persistent build cache volumes.
+.TP
+\fI/var/log/witryna/<site>/<timestamp>.log\fR
+Per\-build log files (site, timestamp, git commit, image, duration, status, stdout, stderr).
+.TP
+\fI/var/log/witryna/<site>/<timestamp>\-hook.log\fR
+Post\-deploy hook output (if configured).
+.SH "SEE ALSO"
+\fBwitryna.toml\fR(5)
+.SH VERSION
+v0.2.0
+.SH AUTHORS
+Dawid Rycerz