misc/genreadme,tempfork/pkgdoc,tsnet: generate README.md files from godocbradtest

Adds a CI check and Makefile target to keep opted-in directories'
README.md files in sync with their package godoc. For now tsnet (and
its sub-packages under tsnet/example) is the only opted-in tree. The
list of directories lives in misc/genreadme/genreadme.go as
defaultRoots, so CI and humans both just run `make genreadme` with no
arguments.

The genreadme workflow runs `make genreadme` and fails if any
README.md is out of date, pointing the user at the same command.

Along the way:

 - tempfork/pkgdoc now emits Markdown instead of plain text: headings
   become level-2 with no {#hdr-...} anchors, and [Symbol] doc links
   resolve to pkg.go.dev URLs, including for symbols in the current
   package (which the default Printer would otherwise emit as bare
   #Name fragments with no backing anchor in a README). Parsing no
   longer uses parser.ImportsOnly, so doc.Package knows the package's
   symbols and can resolve [Symbol] links at all.

 - genreadme also emits a pkg.go.dev Go Reference badge at the top of
   a library package's README; suppressed for package main.

 - tsnet/tsnet.go's package godoc is expanded in idiomatic godoc
   syntax — [Type], [Type.Method], reference-style [link]: URL
   definitions — rather than Markdown-flavored [text](url) or
   backtick-quoted identifiers, so that both pkg.go.dev and the
   generated README.md render cleanly from a single source.

Fixes #19431
Fixes #19483
Fixes #19470

Change-Id: Iade21dc87921ab2bbb65951e5fb373b597fed29e
Signed-off-by: Walter Poupore <walterp@tailscale.com>

8 files changed, 280 insertions, 5 deletions

diff --git a/tsnet/README.md b/tsnet/README.md
new file mode 100644
index 000000000..432e71957
--- /dev/null
+++ b/tsnet/README.md
@@ -0,0 +1,100 @@
+<!-- README.md auto-generated by misc/genreadme; DO NOT EDIT. (or remove this line) -->
+
+# tsnet
+
+[![Go Reference](https://pkg.go.dev/badge/tailscale.com/tsnet.svg)](https://pkg.go.dev/tailscale.com/tsnet)
+
+Package tsnet embeds a Tailscale node directly into a Go program, allowing it to join a tailnet and accept or dial connections without running a separate tailscaled daemon or requiring any system-level configuration.
+
+## Overview
+
+Normally, Tailscale runs as a background system service (tailscaled) that manages a virtual network interface for the whole machine. tsnet takes a different approach: it runs a fully self-contained Tailscale node inside your process using a userspace TCP/IP stack (gVisor). This means:
+
+  - No root privileges required.
+  - No system daemons to install or manage.
+  - Multiple independent Tailscale nodes can run within a single binary.
+  - The node's [Tailscale identity](https://tailscale.com/docs/concepts/tailscale-identity) and state are stored in a directory you control.
+
+The core type is [Server](https://pkg.go.dev/tailscale.com/tsnet#Server), which represents one embedded Tailscale node. Calling [Server.Listen](https://pkg.go.dev/tailscale.com/tsnet#Server.Listen) or [Server.Dial](https://pkg.go.dev/tailscale.com/tsnet#Server.Dial) routes traffic exclusively over the tailnet. The standard library's [net.Listener](https://pkg.go.dev/net#Listener) and [net.Conn](https://pkg.go.dev/net#Conn) interfaces are returned, so any existing Go HTTP server, gRPC server, or other net-based code works without modification.
+
+## Usage
+
+	import "tailscale.com/tsnet"
+
+	s := &tsnet.Server{
+		Hostname: "my-service",
+		AuthKey:  os.Getenv("TS_AUTHKEY"),
+	}
+	defer s.Close()
+
+	ln, err := s.Listen("tcp", ":80")
+	if err != nil {
+		log.Fatal(err)
+	}
+	log.Fatal(http.Serve(ln, myHandler))
+
+On first run, if no [Server.AuthKey](https://pkg.go.dev/tailscale.com/tsnet#Server.AuthKey) is provided and the node is not already enrolled, the server logs an authentication URL. Open it in a browser to add the node to your tailnet.
+
+## Authentication
+
+A [Server](https://pkg.go.dev/tailscale.com/tsnet#Server) authenticates using, in order of precedence:
+
+ 1. [Server.AuthKey](https://pkg.go.dev/tailscale.com/tsnet#Server.AuthKey).
+ 2. The TS\_AUTHKEY environment variable.
+ 3. The TS\_AUTH\_KEY environment variable.
+ 4. An OAuth client secret ([Server.ClientSecret](https://pkg.go.dev/tailscale.com/tsnet#Server.ClientSecret) or TS\_CLIENT\_SECRET), used to mint an auth key.
+ 5. Workload identity federation ([Server.ClientID](https://pkg.go.dev/tailscale.com/tsnet#Server.ClientID) plus [Server.IDToken](https://pkg.go.dev/tailscale.com/tsnet#Server.IDToken) or [Server.Audience](https://pkg.go.dev/tailscale.com/tsnet#Server.Audience)).
+ 6. An interactive login URL printed to [Server.UserLogf](https://pkg.go.dev/tailscale.com/tsnet#Server.UserLogf).
+
+If the node is already enrolled (state found in [Server.Store](https://pkg.go.dev/tailscale.com/tsnet#Server.Store)), the auth key is ignored unless TSNET\_FORCE\_LOGIN=1 is set.
+
+## Identifying callers
+
+Use the WhoIs method on the client returned by [Server.LocalClient](https://pkg.go.dev/tailscale.com/tsnet#Server.LocalClient) to identify who is making a request:
+
+	lc, _ := srv.LocalClient()
+	http.Serve(ln, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		who, err := lc.WhoIs(r.Context(), r.RemoteAddr)
+		if err != nil {
+			http.Error(w, err.Error(), 500)
+			return
+		}
+		fmt.Fprintf(w, "Hello, %s!", who.UserProfile.LoginName)
+	}))
+
+## Tailscale Funnel
+
+[Server.ListenFunnel](https://pkg.go.dev/tailscale.com/tsnet#Server.ListenFunnel) exposes your service on the public internet. [Tailscale Funnel](https://tailscale.com/docs/features/tailscale-funnel) currently supports TCP on ports 443, 8443, and 10000. HTTPS must be enabled in the Tailscale admin console.
+
+	ln, err := srv.ListenFunnel("tcp", ":443")
+	// ln is a TLS listener; connections can come from anywhere on the
+	// internet as well as from your tailnet.
+
+	// To restrict to public traffic only:
+	ln, err = srv.ListenFunnel("tcp", ":443", tsnet.FunnelOnly())
+
+## Tailscale Services
+
+[Server.ListenService](https://pkg.go.dev/tailscale.com/tsnet#Server.ListenService) advertises the node as a host for a named [Tailscale Service](https://tailscale.com/docs/features/tailscale-services). The node must use a tag-based identity. To advertise multiple ports, call ListenService once per port.
+
+	srv.AdvertiseTags = []string{"tag:myservice"}
+
+	ln, err := srv.ListenService("svc:my-service", tsnet.ServiceModeHTTP{
+		HTTPS: true,
+		Port:  443,
+	})
+	log.Printf("Listening on https://%s", ln.FQDN)
+
+## Running multiple nodes in one process
+
+Each [Server](https://pkg.go.dev/tailscale.com/tsnet#Server) instance is an independent node. Give each a unique [Server.Dir](https://pkg.go.dev/tailscale.com/tsnet#Server.Dir) and [Server.Hostname](https://pkg.go.dev/tailscale.com/tsnet#Server.Hostname):
+
+	for _, name := range []string{"frontend", "backend"} {
+		srv := &tsnet.Server{
+			Hostname:  name,
+			Dir:       filepath.Join(baseDir, name),
+			AuthKey:   os.Getenv("TS_AUTHKEY"),
+			Ephemeral: true,
+		}
+		srv.Start()
+	}
diff --git a/tsnet/example/tshello/README.md b/tsnet/example/tshello/README.md
new file mode 100644
index 000000000..5d9d81829
--- /dev/null
+++ b/tsnet/example/tshello/README.md
@@ -0,0 +1,5 @@
+<!-- README.md auto-generated by misc/genreadme; DO NOT EDIT. (or remove this line) -->
+
+# tshello
+
+The tshello server demonstrates how to use Tailscale as a library.
diff --git a/tsnet/example/tsnet-funnel/README.md b/tsnet/example/tsnet-funnel/README.md
new file mode 100644
index 000000000..2b3031bed
--- /dev/null
+++ b/tsnet/example/tsnet-funnel/README.md
@@ -0,0 +1,9 @@
+<!-- README.md auto-generated by misc/genreadme; DO NOT EDIT. (or remove this line) -->
+
+# tsnet-funnel
+
+The tsnet-funnel server demonstrates how to use tsnet with Funnel.
+
+To use it, generate an auth key from the Tailscale admin panel and run the demo with the key:
+
+	TS_AUTHKEY=<yourkey> go run tsnet-funnel.go
diff --git a/tsnet/example/tsnet-http-client/README.md b/tsnet/example/tsnet-http-client/README.md
new file mode 100644
index 000000000..24aba97c8
--- /dev/null
+++ b/tsnet/example/tsnet-http-client/README.md
@@ -0,0 +1,5 @@
+<!-- README.md auto-generated by misc/genreadme; DO NOT EDIT. (or remove this line) -->
+
+# tsnet-http-client
+
+The tshello server demonstrates how to use Tailscale as a library.
diff --git a/tsnet/example/tsnet-services/README.md b/tsnet/example/tsnet-services/README.md
new file mode 100644
index 000000000..18bc072d7
--- /dev/null
+++ b/tsnet/example/tsnet-services/README.md
@@ -0,0 +1,32 @@
+<!-- README.md auto-generated by misc/genreadme; DO NOT EDIT. (or remove this line) -->
+
+# tsnet-services
+
+The tsnet-services example demonstrates how to use tsnet with Services.
+
+To run this example yourself:
+
+ 1. Add access controls which (i) define a new ACL tag, (ii) allow the demo node to host the Service, and (iii) allow peers on the tailnet to reach the Service. A sample ACL policy is provided below.
+ 2. [Generate an auth key](https://tailscale.com/kb/1085/auth-keys#generate-an-auth-key) using the Tailscale admin panel. When doing so, add your new tag to your key (Service hosts must be tagged nodes).
+ 3. [Define a Service](https://tailscale.com/kb/1552/tailscale-services#step-1-define-a-tailscale-service). For the purposes of this demo, it must be defined to listen on TCP port 443. Note that you only need to follow Step 1 in the linked document.
+ 4. Run the demo on the command line (step 4 command shown below).
+
+Command for step 4:
+
+	TS_AUTHKEY=<yourkey> go run tsnet-services.go -service <service-name>
+
+The following is a sample ACL policy for step 1:
+
+	"tagOwners": {
+	   "tag:tsnet-demo-host": ["autogroup:member"],
+	},
+	"autoApprovers": {
+	   "services": {
+	      "svc:tsnet-demo": ["tag:tsnet-demo-host"],
+	   },
+	},
+	"grants": [
+	   "src": ["*"],
+	   "dst": ["svc:tsnet-demo"],
+	   "ip": ["*"],
+	],
diff --git a/tsnet/example/tsnet-services/tsnet-services.go b/tsnet/example/tsnet-services/tsnet-services.go
index d72fd68fd..4604e8d3f 100644
--- a/tsnet/example/tsnet-services/tsnet-services.go
+++ b/tsnet/example/tsnet-services/tsnet-services.go
@@ -8,17 +8,16 @@
 //  1. Add access controls which (i) define a new ACL tag, (ii) allow the demo
 //     node to host the Service, and (iii) allow peers on the tailnet to reach
 //     the Service. A sample ACL policy is provided below.
-//
 //  2. [Generate an auth key] using the Tailscale admin panel. When doing so, add
 //     your new tag to your key (Service hosts must be tagged nodes).
-//
 //  3. [Define a Service]. For the purposes of this demo, it must be defined to
 //     listen on TCP port 443. Note that you only need to follow Step 1 in the
 //     linked document.
+//  4. Run the demo on the command line (step 4 command shown below).
 //
-//  4. Run the demo on the command line:
+// Command for step 4:
 //
-//     TS_AUTHKEY=<yourkey> go run tsnet-services.go -service <service-name>
+//	TS_AUTHKEY=<yourkey> go run tsnet-services.go -service <service-name>
 //
 // The following is a sample ACL policy for step 1:
 //
diff --git a/tsnet/example/web-client/README.md b/tsnet/example/web-client/README.md
new file mode 100644
index 000000000..6b4c42235
--- /dev/null
+++ b/tsnet/example/web-client/README.md
@@ -0,0 +1,5 @@
+<!-- README.md auto-generated by misc/genreadme; DO NOT EDIT. (or remove this line) -->
+
+# web-client
+
+The web-client command demonstrates serving the Tailscale web client over tsnet.
diff --git a/tsnet/tsnet.go b/tsnet/tsnet.go
index f28179773..cc03cdbb6 100644
--- a/tsnet/tsnet.go
+++ b/tsnet/tsnet.go
@@ -1,7 +1,127 @@
 // Copyright (c) Tailscale Inc & contributors
 // SPDX-License-Identifier: BSD-3-Clause
 
-// Package tsnet provides Tailscale as a library.
+// Package tsnet embeds a Tailscale node directly into a Go program,
+// allowing it to join a tailnet and accept or dial connections without
+// running a separate tailscaled daemon or requiring any system-level
+// configuration.
+//
+// # Overview
+//
+// Normally, Tailscale runs as a background system service (tailscaled)
+// that manages a virtual network interface for the whole machine. tsnet
+// takes a different approach: it runs a fully self-contained Tailscale
+// node inside your process using a userspace TCP/IP stack (gVisor).
+// This means:
+//
+//   - No root privileges required.
+//   - No system daemons to install or manage.
+//   - Multiple independent Tailscale nodes can run within a single binary.
+//   - The node's [Tailscale identity] and state are stored in a directory you control.
+//
+// The core type is [Server], which represents one embedded Tailscale
+// node. Calling [Server.Listen] or [Server.Dial] routes traffic
+// exclusively over the tailnet. The standard library's [net.Listener]
+// and [net.Conn] interfaces are returned, so any existing Go HTTP
+// server, gRPC server, or other net-based code works without
+// modification.
+//
+// # Usage
+//
+//	import "tailscale.com/tsnet"
+//
+//	s := &tsnet.Server{
+//		Hostname: "my-service",
+//		AuthKey:  os.Getenv("TS_AUTHKEY"),
+//	}
+//	defer s.Close()
+//
+//	ln, err := s.Listen("tcp", ":80")
+//	if err != nil {
+//		log.Fatal(err)
+//	}
+//	log.Fatal(http.Serve(ln, myHandler))
+//
+// On first run, if no [Server.AuthKey] is provided and the node is not
+// already enrolled, the server logs an authentication URL. Open it in a
+// browser to add the node to your tailnet.
+//
+// # Authentication
+//
+// A [Server] authenticates using, in order of precedence:
+//
+//  1. [Server.AuthKey].
+//  2. The TS_AUTHKEY environment variable.
+//  3. The TS_AUTH_KEY environment variable.
+//  4. An OAuth client secret ([Server.ClientSecret] or TS_CLIENT_SECRET),
+//     used to mint an auth key.
+//  5. Workload identity federation ([Server.ClientID] plus
+//     [Server.IDToken] or [Server.Audience]).
+//  6. An interactive login URL printed to [Server.UserLogf].
+//
+// If the node is already enrolled (state found in [Server.Store]), the
+// auth key is ignored unless TSNET_FORCE_LOGIN=1 is set.
+//
+// # Identifying callers
+//
+// Use the WhoIs method on the client returned by [Server.LocalClient]
+// to identify who is making a request:
+//
+//	lc, _ := srv.LocalClient()
+//	http.Serve(ln, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+//		who, err := lc.WhoIs(r.Context(), r.RemoteAddr)
+//		if err != nil {
+//			http.Error(w, err.Error(), 500)
+//			return
+//		}
+//		fmt.Fprintf(w, "Hello, %s!", who.UserProfile.LoginName)
+//	}))
+//
+// # Tailscale Funnel
+//
+// [Server.ListenFunnel] exposes your service on the public internet.
+// [Tailscale Funnel] currently supports TCP on ports 443, 8443, and
+// 10000. HTTPS must be enabled in the Tailscale admin console.
+//
+//	ln, err := srv.ListenFunnel("tcp", ":443")
+//	// ln is a TLS listener; connections can come from anywhere on the
+//	// internet as well as from your tailnet.
+//
+//	// To restrict to public traffic only:
+//	ln, err = srv.ListenFunnel("tcp", ":443", tsnet.FunnelOnly())
+//
+// # Tailscale Services
+//
+// [Server.ListenService] advertises the node as a host for a named
+// [Tailscale Service]. The node must use a tag-based identity. To
+// advertise multiple ports, call ListenService once per port.
+//
+//	srv.AdvertiseTags = []string{"tag:myservice"}
+//
+//	ln, err := srv.ListenService("svc:my-service", tsnet.ServiceModeHTTP{
+//		HTTPS: true,
+//		Port:  443,
+//	})
+//	log.Printf("Listening on https://%s", ln.FQDN)
+//
+// # Running multiple nodes in one process
+//
+// Each [Server] instance is an independent node. Give each a unique
+// [Server.Dir] and [Server.Hostname]:
+//
+//	for _, name := range []string{"frontend", "backend"} {
+//		srv := &tsnet.Server{
+//			Hostname:  name,
+//			Dir:       filepath.Join(baseDir, name),
+//			AuthKey:   os.Getenv("TS_AUTHKEY"),
+//			Ephemeral: true,
+//		}
+//		srv.Start()
+//	}
+//
+// [Tailscale identity]: https://tailscale.com/docs/concepts/tailscale-identity
+// [Tailscale Funnel]: https://tailscale.com/docs/features/tailscale-funnel
+// [Tailscale Service]: https://tailscale.com/docs/features/tailscale-services
 package tsnet
 
 import (