Add puppet virtual repositories

docs/puppet/remote.md

@@ -5,3 +5,6 @@ Shared classification, TTL and eviction rules: [caching](../common/caching.md).
 | Type | Mutable (auto-detected) | Immutable (auto-detected) |
 |---|---|---|
 | `puppet` | `v3/modules/*`, `v3/releases*` | `.tar.gz` |
+
+`/v3/releases` forwards the `module`, `limit` and `offset` query params
+upstream; set `base_url` to the Forge API root, e.g. `https://forgeapi.puppet.com`.

docs/puppet/virtual.md

@@ -0,0 +1,37 @@
+# `puppet` virtual
+
+A puppet virtual serves one Forge v3 API over local and remote puppet members:
+`puppet module install` and r10k work against `/api/v1/virtual/<name>`, with
+dependencies resolved across members.
+
+- `/v3/releases?module=<slug>` merges member releases; on a duplicate version
+  the earlier member wins. Releases are newest first, paginated with
+  `limit` (up to 100) and `offset`; pagination links and `file_uri` are
+  relative to the Forge root, so downloads route via the virtual.
+- `/v3/modules/<slug>` lists the merged releases with the highest version as
+  `current_release`.
+- `/v3/releases/<slug>-<version>` and `/v3/files/<file>` 302 to the member
+  owning that release.
+- A member error fails the request with 502; a member without the module is
+  skipped. Merges are cached for 60s.
+
+```hcl
+resource "artifactapi_virtual" "puppet" {
+  name         = "puppet"
+  package_type = "puppet"
+  members      = [artifactapi_local_puppet.internal.name, artifactapi_remote_puppet.forge.name]
+}
+```
+
+```bash
+puppet module install unkin-hello \
+  --module_repository https://artifactapi.example.com/api/v1/virtual/puppet
+```
+
+```yaml
+# r10k.yaml
+forge:
+  baseurl: https://artifactapi.example.com/api/v1/virtual/puppet
+```
+
+Upload to the local member directly; the virtual is read-only.