docs: restructure into a Diataxis tree with a generated CLI reference

The site was ~3,500 words for a project with ~90 CLI flags, and several
of those words were wrong: --peerguardian is not a flag, the egress and
`edgevpn start` features were undocumented entirely, and the architecture
page described a ledger that had been replaced.

Restructures docs/content into tutorials / how-to / reference /
explanation, with a Hugo alias on every moved page so existing inbound
links keep working.

Adds internal/docsgen, which walks the real cli.App via cmd.NewApp and
emits the CLI and environment-variable reference. A CI job regenerates
and diffs it, so a flag cannot be added without the docs following. That
covers 94 flags and 85 environment variables that were previously
undocumented, and makes the --peerguardian class of defect structurally
impossible.

Publishes docs/design/authenticated-ledger.md, which had never shipped,
and adds guides for HTTP egress, ledger ownership, relays, Docker and the
ledger bucket namespace, plus a security model page stating plainly that
EdgeVPN's model is perimeter-only.

Relocates the README's unique content to the site and trims it. The
README's Go library example did not compile; it does now.

Also removes the unused docsy git submodule, adds the missing
CONTRIBUTING.md the docs linked to, reconciles baseURL with what
production actually serves, and fixes a 404 page that redirected
visitors off-site.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: mudler

.github/dependabot.yml

@@ -1,10 +1,6 @@
 # https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
 version: 2
 updates:
-  - package-ecosystem: "gitsubmodule"
-    directory: "/"
-    schedule:
-      interval: "weekly"
   - package-ecosystem: "gomod"
     directory: "/"
     schedule:

.github/workflows/docs-gen.yml

@@ -0,0 +1,33 @@
+name: Docs reference drift
+
+on:
+  # Narrowed to master: an unfiltered `push` also fires on every topic branch
+  # and every tag, duplicating the run each pull request already performs.
+  push:
+    branches: [ master ]
+  pull_request:
+
+jobs:
+  docs-gen:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+      - name: Set up Go
+        uses: actions/setup-go@v6
+        with:
+          go-version: 1.26
+      - name: Regenerate the reference
+        run: make docs-gen
+      - name: Fail if the generated reference is stale
+        # The output is staged before diffing because `git diff --exit-code`
+        # ignores untracked paths: a brand-new command makes the generator emit
+        # a new cli/<name>.md, and an unstaged diff would pass while that page
+        # went uncommitted. Diffing the index catches additions alongside
+        # modifications and deletions.
+        run: |
+          git add -A docs/content/en/docs/reference/
+          if ! git diff --cached --exit-code docs/content/en/docs/reference/; then
+            echo "::error::The generated CLI reference is out of date. Run 'make docs-gen' and commit the result."
+            exit 1
+          fi

.github/workflows/pages.yml

@@ -2,6 +2,11 @@ name: Github Pages
 on:
   push:
     branches: [ master ]
+  # Pull requests build the docs so breakage is caught before merge. They must
+  # never deploy: the Deploy step below is guarded on a push to master.
+  pull_request:
+    paths:
+      - 'docs/**'
 
 jobs:
   build:

.gitmodules

@@ -0,0 +1,66 @@
+# Contributing to EdgeVPN
+
+Thanks for wanting to help. This page is the short version; the full
+documentation lives at <https://mudler.github.io/edgevpn/docs/>.
+
+## Build
+
+EdgeVPN is a single Go binary. You need Go 1.26 (the version in `go.mod`) and
+nothing else:
+
+```bash
+make build      # go build -o edgevpn ./
+```
+
+Building the **documentation site** additionally needs Hugo and Node/npm —
+`docs/scripts/build.sh` downloads the pinned Hugo (see `docs/Makefile`) and
+installs `postcss-cli` and `autoprefixer` for you:
+
+```bash
+cd docs && make build   # one-off build into docs/public
+cd docs && make serve   # live preview on http://localhost:1313
+```
+
+## Test
+
+```bash
+make test       # go test ./...
+```
+
+The end-to-end suites that CI runs (VPN connectivity, services, file transfer)
+are the scripts under `.github/`; see `.github/workflows/test.yml` for how they
+are invoked.
+
+## Adding or changing a CLI flag
+
+The CLI and environment-variable reference under
+`docs/content/en/docs/reference/` is **generated** from the real `cli.App` — do
+not hand-edit those pages. After touching any flag or command, run:
+
+```bash
+make docs-gen
+```
+
+and commit the result. The `Docs reference drift` workflow regenerates the
+reference on every push and pull request and fails if the committed output
+differs, so a forgotten `make docs-gen` will turn CI red.
+
+## Issues and pull requests
+
+- Open issues and feature requests at
+  <https://github.com/mudler/edgevpn/issues>.
+- Questions and general discussion belong in
+  [GitHub Discussions](https://github.com/mudler/edgevpn/discussions) or the
+  [Matrix room](https://matrix.to/#/#edgevpn:matrix.org).
+- Pull requests go against `master`. Please make sure `make test` and
+  `make docs-gen` are clean before asking for review, and mark work in progress
+  with a draft PR or a `WIP` prefix.
+
+Docs-only changes have their own walkthrough (including the *Edit this page*
+shortcut) at
+<https://mudler.github.io/edgevpn/docs/contribution-guidelines/>.
+
+## License
+
+EdgeVPN is Apache 2.0 licensed. By contributing you agree that your
+contributions are licensed under the same terms.

CONTRIBUTING.md

@@ -0,0 +1,13 @@
+.PHONY: build test docs-gen
+
+build:
+	go build -o edgevpn ./
+
+test:
+	go test ./...
+
+# docs-gen regenerates the CLI and environment-variable reference from the real
+# cli.App. The output is committed; CI re-runs this and fails on a diff, so the
+# docs cannot drift from the binary.
+docs-gen:
+	go run ./internal/docsgen

Makefile

@@ -32,7 +32,7 @@ It can:
 - **Create a VPN** :  Secure VPN between p2p peers
   - Automatically assign IPs to nodes
   - Embedded tiny DNS server to resolve internal/external IPs
-  - Create trusted zones to prevent network access if token is leaked
+  - Create trusted zones to restrict which peers may join (experimental: it does not currently stop a token holder from entering the zone — see the [security model](https://mudler.github.io/edgevpn/docs/explanation/security-model/))
   - For example, the [Kairos](https://github.com/kairos-io/kairos) CNCF project uses it as a layer for creating decentralized clusters with Kubernetes
 
 - **Act as a reverse Proxy** : Share a tcp service like you would do with `ngrok`. EdgeVPN let expose TCP services to the p2p network nodes without establishing a VPN connection: creates reverse proxy and tunnels traffic into the p2p network.
@@ -75,6 +75,14 @@ Check out [Kairos](https://github.com/kairos-io/kairos) for seeing EdgeVPN in ac
 
 Download the precompiled static release in the [releases page](https://github.com/mudler/edgevpn/releases). You can either install it in your system or just run it.
 
+Or install the latest release with the one-liner:
+
+```bash
+curl -sfL https://raw.githubusercontent.com/mudler/edgevpn/master/install.sh | sh
+```
+
+Every installation route — install script, release archives, Homebrew, the container image and building from source — is covered in [Install EdgeVPN](https://mudler.github.io/edgevpn/docs/tutorials/install/).
+
 # :computer: Usage
 
 EdgeVPN works by generating tokens (or a configuration file) that can be shared between different machines, hosts or peers to access to a decentralized secured network between them.
@@ -129,90 +137,20 @@ $ EDGEVPNTOKEN=.. edgevpn --address 10.1.0.13/24
 
 # :question: Is it for me?
 
-EdgeVPN makes VPN decentralization a first strong requirement. 
-
-Its main use is for edge and low-end devices and especially for development.
-
-The decentralized approach has few cons:
-
-- The underlying network is chatty. It uses a Gossip protocol for synchronizing the routing table and p2p. Every blockchain message is broadcasted to all peers, while the traffic is to the host only.
-- Might be not suited for low latency workload.
-
-Keep that in mind before using it for your prod networks!
-
-But it has a strong pro: it just works everywhere libp2p works!
+The decentralized approach is chatty and might not suit low-latency workloads, and this software has not been security audited. Read [when not to use EdgeVPN](https://mudler.github.io/edgevpn/docs/explanation/when-not-to-use-edgevpn/) before you rely on it.
 
 # :question: Why? 
 
 First of all it's my first experiment with libp2p. Second, I always wanted a more "open" `ngrok` alternative, but I always prefer to have "less infra" as possible to maintain. That's why building something like this on top of `libp2p` makes sense.
 
 # :warning: Warning!
 
-I'm not a security expert, and this software didn't went through a full security audit, so don't use and rely on it for sensible traffic and not even for production environment! I did this mostly for fun while I was experimenting with libp2p. 
-
-## Example use case: network-decentralized [k3s](https://github.com/k3s-io/k3s) test cluster
-
-Let's see a practical example, you are developing something for kubernetes and you want to try a multi-node setup, but you have machines available that are only behind NAT (pity!) and you would really like to leverage HW.
-
-If you are not really interested in network performance (again, that's for development purposes only!) then you could use `edgevpn` + [k3s](https://github.com/k3s-io/k3s) in this way:
-
-1) Generate edgevpn config: `edgevpn -g > vpn.yaml`
-2) Start the vpn:
-
-   on node A: `sudo IFACE=edgevpn0 ADDRESS=10.1.0.3/24 EDGEVPNCONFIG=vpn.yml edgevpn`
-   
-   on node B: `sudo IFACE=edgevpn0 ADDRESS=10.1.0.4/24 EDGEVPNCONFIG=vpm.yml edgevpn`
-3) Start k3s:
- 
-   on node A: `k3s server --flannel-iface=edgevpn0`
-   
-   on node B: `K3S_URL=https://10.1.0.3:6443 K3S_TOKEN=xx k3s agent --flannel-iface=edgevpn0 --node-ip 10.1.0.4`
-
-We have used flannel here, but other CNI should work as well.
-
-
-# :notebook: As a library
-
-EdgeVPN can be used as a library. It is very portable and offers a functional interface.
-
-To join a node in a network from a token, without starting the vpn:
-
-```golang
+This software has not been through a full security audit — don't rely on it for sensitive traffic or production environments. The full caveats are in [when not to use EdgeVPN](https://mudler.github.io/edgevpn/docs/explanation/when-not-to-use-edgevpn/).
 
-import (
-    node "github.com/mudler/edgevpn/pkg/node"
-)
+# :books: Examples
 
-e := node.New(
-    node.Logger(l),
-    node.LogLevel(log.LevelInfo),
-    node.MaxMessageSize(2 << 20),
-    node.FromBase64( mDNSEnabled, DHTEnabled, token ),
-    // ....
-  )
-
-e.Start(ctx)
-
-```
-
-or to start a VPN:
-
-```golang
-
-import (
-    vpn "github.com/mudler/edgevpn/pkg/vpn"
-    node "github.com/mudler/edgevpn/pkg/node"
-)
-
-opts, err := vpn.Register(vpnOpts...)
-if err != nil {
-	return err
-}
-
-e := edgevpn.New(append(o, opts...)...)
-
-e.Start(ctx)
-```
+- [A network-decentralized k3s test cluster](https://mudler.github.io/edgevpn/docs/tutorials/decentralized-k3s-cluster/) — a multi-node Kubernetes development cluster across machines behind NAT.
+- [Use EdgeVPN as a library](https://mudler.github.io/edgevpn/docs/how-to/use-as-a-library/) — embed a node in your own Go program.
 
 # 🧑‍💻 Projects using EdgeVPN
 
@@ -239,23 +177,7 @@ and any other way if not mentioned here.
 
 # :notebook: Troubleshooting
 
-If during bootstrap you see messages like:
-
-```
-edgevpn[3679]:             * [/ip4/104.131.131.82/tcp/4001] failed to negotiate stream multiplexer: context deadline exceeded     
-```
-
-or
-
-```
-edgevpn[9971]: 2021/12/16 20:56:34 failed to sufficiently increase receive buffer size (was: 208 kiB, wanted: 2048 kiB, got: 416 kiB). See https://github.com/lucas-clemente/quic-go/wiki/UDP-Receive-Buffer-Size for details.
-```
-
-or generally experiencing poor network performance, it is recommended to increase the maximum buffer size by running:
-
-```
-sysctl -w net.core.rmem_max=2500000
-```
+Bootstrap failures, receive-buffer warnings and poor network performance are covered in [Troubleshooting](https://mudler.github.io/edgevpn/docs/troubleshooting/).
 
 # :notebook: TODO
 

README.md

@@ -1,4 +1,7 @@
-baseURL = "https://mudler.github.io/edgevpn/docs/"
+# Must match the -b value passed by scripts/build.sh, which is what production
+# is actually built with. The site root is https://mudler.github.io/edgevpn/;
+# /docs/ is a content section inside it, not the base.
+baseURL = "https://mudler.github.io/edgevpn/"
 title = "EdgeVPN"
 
 enableRobotsTXT = true
@@ -42,10 +45,9 @@ resampleFilter = "CatmullRom"
 quality = 75
 anchor = "smart"
 
-[services]
-[services.googleAnalytics]
-# Comment out the next line to disable GA tracking. Also disables the feature described in [params.ui.feedback].
-id = "UA-00000000-0"
+# No analytics property is configured. The Docsy template ships a placeholder
+# "UA-00000000-0" here; leaving it in place sent page views and the
+# [params.ui.feedback] events to a property that does not exist.
 
 # Language configuration
 
@@ -118,8 +120,9 @@ offlineSearch = true
 [params.ui]
 # Enable to show the side bar menu in its compact state.
 sidebar_menu_compact = false
-#  Set to true to disable breadcrumb navigation.
-breadcrumb_disable = true
+#  Set to true to disable breadcrumb navigation. The docs tree is three levels
+#  deep (docs / section / page), so breadcrumbs earn their keep.
+breadcrumb_disable = false
 #  Set to true to hide the sidebar search box (the top nav search box will still be displayed if search is enabled)
 sidebar_search_disable = false
 #  Set to false if you don't want to display a logo (/assets/icons/logo.svg) in the top nav bar
@@ -131,8 +134,11 @@ footer_about_disable = false
 # This feature depends on [services.googleAnalytics] and will be disabled if "services.googleAnalytics.id" is not set.
 # If you want this feature, but occasionally need to remove the "Feedback" section from a single page,
 # add "hide_feedback: true" to the page's front matter.
+# Disabled along with the analytics property above: the responses are delivered
+# as Google Analytics events, so with no property configured the widget would
+# only collect clicks and drop them. Re-enable once a GA4 property exists.
 [params.ui.feedback]
-enable = true
+enable = false
 # The responses that the user sees after clicking "yes" (the page was helpful) or "no" (the page was not helpful).
 yes = 'Glad to hear it! Please <a href="https://github.com/mudler/edgevpn/issues/new">tell us how we can improve</a>.'
 no = 'Sorry to hear that. Please <a href="https://github.com/mudler/edgevpn/issues/new">tell us how we can improve</a>.'

docs/config.toml

@@ -71,10 +71,10 @@ <h1 class="text-center">
 </h1>
 
 <center>
-	<a class="btn btn-md btn-primary mr-3 mb-4" href="{{< relref "/docs">}}/getting-started/api/">
+	<a class="btn btn-md btn-primary mr-3 mb-4" href="{{< relref "/docs/reference/api" >}}">
 		WebUI
 		<i class="fa fa-globe ml-2"></i></a>
-		<a class="btn btn-md btn-primary mr-3 mb-4" href="{{< relref "/docs">}}/getting-started/gui/">GUI
+		<a class="btn btn-md btn-primary mr-3 mb-4" href="{{< relref "/docs/tools/desktop-gui" >}}">GUI
 		<i class="fa fa-desktop ml-2"></i></a><br>
 	Keep an eye on your network with the Web UI. <br>
 	Connect easily from your workstation with the frontend GUI app.