Orbit documentation: docs, wiki and FAQ pages

docs/push-to-deploy.md

@@ -0,0 +1,38 @@
+# Push-to-deploy
+
+Orbit ships its own self-hosted git workflow: a `git push` runs the tests, builds, and publishes —
+no external CI required.
+
+## How it works
+
+A **bare git repo** on the server has a `post-receive` hook. On a push to `main` it:
+
+1. Checks out the new commit.
+2. Runs `npm ci && npm run test && npm run build` — **gated**, so a broken push never ships.
+3. Publishes `dist/` to the web root with `rsync --delete` (keeping a backup for rollback).
+
+The whole loop is one command:
+
+```sh
+git commit -m "…"
+git push          # test → build → deploy (+ mirror)
+```
+
+## The hook (sketch)
+
+```bash
+#!/bin/bash
+set -e; unset GIT_DIR
+WORK=/path/to/checkout; WEBROOT=/var/www/site/app
+while read -r _old new ref; do
+  [ "$ref" = "refs/heads/main" ] || continue
+  cd "$WORK"; git fetch -q self; git reset --hard -q self/main
+  npm ci --silent && npm run test && npm run build
+  rsync -a --delete dist/ "$WEBROOT/"
+done
+```
+
+## Bonus: IRC announcements
+
+The same hook hands the commit list to a small bot that posts a GitHub-style summary to the
+project's IRC channel. See [The #orbit channel & bot](/wiki/orbit-channel/).