merge main

docs/data-sources/remote.md

@@ -0,0 +1,9 @@
+# `artifactapi_remote` (Data Source)
+
+Read an existing remote's configuration.
+
+```hcl
+data "artifactapi_remote" "dockerhub" {
+  name = "dockerhub"
+}
+```

docs/data-sources/virtual.md

@@ -0,0 +1,9 @@
+# `artifactapi_virtual` (Data Source)
+
+Read an existing virtual repository's configuration.
+
+```hcl
+data "artifactapi_virtual" "helm" {
+  name = "helm"
+}
+```

docs/resources/local_alpine.md

@@ -0,0 +1,11 @@
+# `artifactapi_local_alpine`
+
+Local resources manage repositories that ArtifactAPI hosts directly (rather than
+proxying an upstream) — each is a real registry for its package type.
+
+Each takes just `name` (required, forces replacement) and an optional
+`description`.
+
+## Example
+
+See `examples/resources/artifactapi_local_alpine/main.tf`.

docs/resources/local_ansible.md

@@ -0,0 +1,13 @@
+# `artifactapi_local_ansible`
+
+Local resources manage repositories that ArtifactAPI hosts directly (rather than
+proxying an upstream) — each is a real registry for its package type.
+
+A Galaxy v3 server for collections (`ansible-galaxy collection publish` and `install`).
+
+Each takes just `name` (required, forces replacement) and an optional
+`description`.
+
+## Example
+
+See `examples/resources/artifactapi_local_ansible/main.tf`.

docs/resources/local_deb.md

@@ -0,0 +1,11 @@
+# `artifactapi_local_deb`
+
+Local resources manage repositories that ArtifactAPI hosts directly (rather than
+proxying an upstream) — each is a real registry for its package type.
+
+Each takes just `name` (required, forces replacement) and an optional
+`description`.
+
+## Example
+
+See `examples/resources/artifactapi_local_deb/main.tf`.

docs/resources/local_docker.md

@@ -0,0 +1,21 @@
+# `artifactapi_local_docker`
+
+Local resources manage repositories that ArtifactAPI hosts directly (rather than
+proxying an upstream) — each is a real registry for its package type.
+
+A container registry (Docker Registry HTTP API V2, push and pull).
+
+Each takes just `name` (required, forces replacement) and an optional
+`description`.
+
+## Example
+
+```hcl
+resource "artifactapi_local_docker" "internal" {
+  name        = "docker-internal"
+  description = "Internal container image registry"
+}
+```
+
+Images push and pull against `<endpoint>/<name>/<image>:<tag>`, e.g.
+`docker push artifactapi.example.com/docker-internal/myapp:latest`.

docs/resources/local_gems.md

@@ -0,0 +1,13 @@
+# `artifactapi_local_gems`
+
+Local resources manage repositories that ArtifactAPI hosts directly (rather than
+proxying an upstream) — each is a real registry for its package type.
+
+A RubyGems source (`gem push`, `gem yank`, `gem install` and `bundle install`).
+
+Each takes just `name` (required, forces replacement) and an optional
+`description`.
+
+## Example
+
+See `examples/resources/artifactapi_local_gems/main.tf`.

docs/resources/local_generic.md

@@ -0,0 +1,11 @@
+# `artifactapi_local_generic`
+
+Local resources manage repositories that ArtifactAPI hosts directly (rather than
+proxying an upstream) — each is a real registry for its package type.
+
+Each takes just `name` (required, forces replacement) and an optional
+`description`.
+
+## Example
+
+See `examples/resources/artifactapi_local_generic/main.tf`.

docs/resources/local_goproxy.md

@@ -0,0 +1,13 @@
+# `artifactapi_local_goproxy`
+
+Local resources manage repositories that ArtifactAPI hosts directly (rather than
+proxying an upstream) — each is a real registry for its package type.
+
+A Go module proxy for private modules (GOPROXY protocol: `go get`, `go mod download`).
+
+Each takes just `name` (required, forces replacement) and an optional
+`description`.
+
+## Example
+
+See `examples/resources/artifactapi_local_goproxy/main.tf`.

docs/resources/local_helm.md

@@ -0,0 +1,13 @@
+# `artifactapi_local_helm`
+
+Local resources manage repositories that ArtifactAPI hosts directly (rather than
+proxying an upstream) — each is a real registry for its package type.
+
+A chart repository (index.yaml generated from uploaded charts).
+
+Each takes just `name` (required, forces replacement) and an optional
+`description`.
+
+## Example
+
+See `examples/resources/artifactapi_local_helm/main.tf`.

docs/resources/local_npm.md

@@ -0,0 +1,13 @@
+# `artifactapi_local_npm`
+
+Local resources manage repositories that ArtifactAPI hosts directly (rather than
+proxying an upstream) — each is a real registry for its package type.
+
+An npm registry (`npm publish` and `npm install`).
+
+Each takes just `name` (required, forces replacement) and an optional
+`description`.
+
+## Example
+
+See `examples/resources/artifactapi_local_npm/main.tf`.

docs/resources/local_pypi.md

@@ -0,0 +1,11 @@
+# `artifactapi_local_pypi`
+
+Local resources manage repositories that ArtifactAPI hosts directly (rather than
+proxying an upstream) — each is a real registry for its package type.
+
+Each takes just `name` (required, forces replacement) and an optional
+`description`.
+
+## Example
+
+See `examples/resources/artifactapi_local_pypi/main.tf`.

docs/resources/local_rpm.md

@@ -0,0 +1,11 @@
+# `artifactapi_local_rpm`
+
+Local resources manage repositories that ArtifactAPI hosts directly (rather than
+proxying an upstream) — each is a real registry for its package type.
+
+Each takes just `name` (required, forces replacement) and an optional
+`description`.
+
+## Example
+
+See `examples/resources/artifactapi_local_rpm/main.tf`.

docs/resources/local_terraform.md

@@ -0,0 +1,11 @@
+# `artifactapi_local_terraform`
+
+Local resources manage repositories that ArtifactAPI hosts directly (rather than
+proxying an upstream) — each is a real registry for its package type.
+
+Each takes just `name` (required, forces replacement) and an optional
+`description`.
+
+## Example
+
+See `examples/resources/artifactapi_local_terraform/main.tf`.

docs/resources/remote_alpine.md

@@ -0,0 +1,53 @@
+# `artifactapi_remote_alpine`
+
+Per-type remote resources manage upstream repository proxies. Each type applies its own mutability classification rules automatically (e.g., Docker classifies tag manifests as mutable and blobs as immutable; Helm classifies `index.yaml` as mutable).
+
+## Common Attributes
+
+| Attribute            | Required | Default | Description                                                       |
+|----------------------|----------|---------|-------------------------------------------------------------------|
+| `name`               | Yes      |         | Unique name (forces replacement on change)                        |
+| `base_url`           | Yes      |         | Upstream repository URL                                           |
+| `description`        | No       | `""`    | Human-readable description                                        |
+| `username`           | No       | `""`    | Upstream auth username (sensitive)                                 |
+| `password`           | No       | `""`    | Upstream auth password (sensitive)                                 |
+| `immutable_ttl`      | No       | `0`     | TTL in seconds for immutable artifacts (0 = cache forever)        |
+| `mutable_ttl`        | No       | `3600`  | TTL in seconds for mutable artifacts                              |
+| `check_mutable`      | No       | `true`  | Enable conditional revalidation for mutable artifacts             |
+| `patterns`           | No       |         | Allowlist of path patterns to proxy (empty = all)                 |
+| `blocklist`          | No       |         | Paths to always deny (checked before patterns)                    |
+| `mutable_patterns`   | No       |         | Override: treat matching paths as mutable                         |
+| `immutable_patterns` | No       |         | Override: treat matching paths as immutable                       |
+| `quarantine_enabled` | No       | `false` | Enable quarantine for new artifacts                               |
+| `quarantine_days`    | No       | `3`     | Days to quarantine new artifacts                                  |
+| `stale_on_error`     | No       | `true`  | Serve stale cache when upstream is unreachable                    |
+| `upstream_dial_timeout` | No    | `0`     | Upstream TCP connect timeout in seconds (0 = server default)      |
+| `upstream_tls_timeout` | No     | `0`     | Upstream TLS handshake timeout in seconds (0 = server default)    |
+| `upstream_response_header_timeout` | No | `0` | Upstream response-header timeout in seconds (0 = server default) |
+
+## rpm / deb / alpine-specific Attributes
+
+| Attribute         | Default       | Description                                                                                     |
+|-------------------|---------------|-------------------------------------------------------------------------------------------------|
+| `mirrorlist`      |               | Extra upstream mirror base URLs. Requests are load-balanced with failover across `base_url` + `mirrorlist`. |
+| `mirror_strategy` | `round_robin` | Mirror load-balancing strategy across `base_url` + `mirrorlist`. One of `round_robin` or `least_conn`. |
+
+Only valid on the `artifactapi_remote_rpm`, `artifactapi_remote_deb`, and
+`artifactapi_remote_alpine` resources. Setting either on any other remote type is
+rejected at plan time.
+
+```hcl
+resource "artifactapi_remote_rpm" "epel" {
+  name     = "epel-9"
+  base_url = "https://download.example.com/pub/epel/9/Everything/x86_64"
+  mirrorlist = [
+    "https://mirror-a.example.net/epel/9/Everything/x86_64",
+    "https://mirror-b.example.org/epel/9/Everything/x86_64",
+  ]
+  mirror_strategy = "least_conn"
+}
+```
+
+## Example
+
+See `examples/resources/artifactapi_remote_alpine/main.tf`.

docs/resources/remote_ansible.md

@@ -0,0 +1,30 @@
+# `artifactapi_remote_ansible`
+
+Per-type remote resources manage upstream repository proxies. Each type applies its own mutability classification rules automatically (e.g., Docker classifies tag manifests as mutable and blobs as immutable; Helm classifies `index.yaml` as mutable).
+
+## Common Attributes
+
+| Attribute            | Required | Default | Description                                                       |
+|----------------------|----------|---------|-------------------------------------------------------------------|
+| `name`               | Yes      |         | Unique name (forces replacement on change)                        |
+| `base_url`           | Yes      |         | Upstream repository URL                                           |
+| `description`        | No       | `""`    | Human-readable description                                        |
+| `username`           | No       | `""`    | Upstream auth username (sensitive)                                 |
+| `password`           | No       | `""`    | Upstream auth password (sensitive)                                 |
+| `immutable_ttl`      | No       | `0`     | TTL in seconds for immutable artifacts (0 = cache forever)        |
+| `mutable_ttl`        | No       | `3600`  | TTL in seconds for mutable artifacts                              |
+| `check_mutable`      | No       | `true`  | Enable conditional revalidation for mutable artifacts             |
+| `patterns`           | No       |         | Allowlist of path patterns to proxy (empty = all)                 |
+| `blocklist`          | No       |         | Paths to always deny (checked before patterns)                    |
+| `mutable_patterns`   | No       |         | Override: treat matching paths as mutable                         |
+| `immutable_patterns` | No       |         | Override: treat matching paths as immutable                       |
+| `quarantine_enabled` | No       | `false` | Enable quarantine for new artifacts                               |
+| `quarantine_days`    | No       | `3`     | Days to quarantine new artifacts                                  |
+| `stale_on_error`     | No       | `true`  | Serve stale cache when upstream is unreachable                    |
+| `upstream_dial_timeout` | No    | `0`     | Upstream TCP connect timeout in seconds (0 = server default)      |
+| `upstream_tls_timeout` | No     | `0`     | Upstream TLS handshake timeout in seconds (0 = server default)    |
+| `upstream_response_header_timeout` | No | `0` | Upstream response-header timeout in seconds (0 = server default) |
+
+## Example
+
+See `examples/resources/artifactapi_remote_ansible/main.tf`.

docs/resources/remote_cargo.md

@@ -0,0 +1,30 @@
+# `artifactapi_remote_cargo`
+
+Per-type remote resources manage upstream repository proxies. Each type applies its own mutability classification rules automatically (e.g., Docker classifies tag manifests as mutable and blobs as immutable; Helm classifies `index.yaml` as mutable).
+
+## Common Attributes
+
+| Attribute            | Required | Default | Description                                                       |
+|----------------------|----------|---------|-------------------------------------------------------------------|
+| `name`               | Yes      |         | Unique name (forces replacement on change)                        |
+| `base_url`           | Yes      |         | Upstream repository URL                                           |
+| `description`        | No       | `""`    | Human-readable description                                        |
+| `username`           | No       | `""`    | Upstream auth username (sensitive)                                 |
+| `password`           | No       | `""`    | Upstream auth password (sensitive)                                 |
+| `immutable_ttl`      | No       | `0`     | TTL in seconds for immutable artifacts (0 = cache forever)        |
+| `mutable_ttl`        | No       | `3600`  | TTL in seconds for mutable artifacts                              |
+| `check_mutable`      | No       | `true`  | Enable conditional revalidation for mutable artifacts             |
+| `patterns`           | No       |         | Allowlist of path patterns to proxy (empty = all)                 |
+| `blocklist`          | No       |         | Paths to always deny (checked before patterns)                    |
+| `mutable_patterns`   | No       |         | Override: treat matching paths as mutable                         |
+| `immutable_patterns` | No       |         | Override: treat matching paths as immutable                       |
+| `quarantine_enabled` | No       | `false` | Enable quarantine for new artifacts                               |
+| `quarantine_days`    | No       | `3`     | Days to quarantine new artifacts                                  |
+| `stale_on_error`     | No       | `true`  | Serve stale cache when upstream is unreachable                    |
+| `upstream_dial_timeout` | No    | `0`     | Upstream TCP connect timeout in seconds (0 = server default)      |
+| `upstream_tls_timeout` | No     | `0`     | Upstream TLS handshake timeout in seconds (0 = server default)    |
+| `upstream_response_header_timeout` | No | `0` | Upstream response-header timeout in seconds (0 = server default) |
+
+## Example
+
+See `examples/resources/artifactapi_remote_cargo/main.tf`.

docs/resources/remote_deb.md

@@ -0,0 +1,53 @@
+# `artifactapi_remote_deb`
+
+Per-type remote resources manage upstream repository proxies. Each type applies its own mutability classification rules automatically (e.g., Docker classifies tag manifests as mutable and blobs as immutable; Helm classifies `index.yaml` as mutable).
+
+## Common Attributes
+
+| Attribute            | Required | Default | Description                                                       |
+|----------------------|----------|---------|-------------------------------------------------------------------|
+| `name`               | Yes      |         | Unique name (forces replacement on change)                        |
+| `base_url`           | Yes      |         | Upstream repository URL                                           |
+| `description`        | No       | `""`    | Human-readable description                                        |
+| `username`           | No       | `""`    | Upstream auth username (sensitive)                                 |
+| `password`           | No       | `""`    | Upstream auth password (sensitive)                                 |
+| `immutable_ttl`      | No       | `0`     | TTL in seconds for immutable artifacts (0 = cache forever)        |
+| `mutable_ttl`        | No       | `3600`  | TTL in seconds for mutable artifacts                              |
+| `check_mutable`      | No       | `true`  | Enable conditional revalidation for mutable artifacts             |
+| `patterns`           | No       |         | Allowlist of path patterns to proxy (empty = all)                 |
+| `blocklist`          | No       |         | Paths to always deny (checked before patterns)                    |
+| `mutable_patterns`   | No       |         | Override: treat matching paths as mutable                         |
+| `immutable_patterns` | No       |         | Override: treat matching paths as immutable                       |
+| `quarantine_enabled` | No       | `false` | Enable quarantine for new artifacts                               |
+| `quarantine_days`    | No       | `3`     | Days to quarantine new artifacts                                  |
+| `stale_on_error`     | No       | `true`  | Serve stale cache when upstream is unreachable                    |
+| `upstream_dial_timeout` | No    | `0`     | Upstream TCP connect timeout in seconds (0 = server default)      |
+| `upstream_tls_timeout` | No     | `0`     | Upstream TLS handshake timeout in seconds (0 = server default)    |
+| `upstream_response_header_timeout` | No | `0` | Upstream response-header timeout in seconds (0 = server default) |
+
+## rpm / deb / alpine-specific Attributes
+
+| Attribute         | Default       | Description                                                                                     |
+|-------------------|---------------|-------------------------------------------------------------------------------------------------|
+| `mirrorlist`      |               | Extra upstream mirror base URLs. Requests are load-balanced with failover across `base_url` + `mirrorlist`. |
+| `mirror_strategy` | `round_robin` | Mirror load-balancing strategy across `base_url` + `mirrorlist`. One of `round_robin` or `least_conn`. |
+
+Only valid on the `artifactapi_remote_rpm`, `artifactapi_remote_deb`, and
+`artifactapi_remote_alpine` resources. Setting either on any other remote type is
+rejected at plan time.
+
+```hcl
+resource "artifactapi_remote_rpm" "epel" {
+  name     = "epel-9"
+  base_url = "https://download.example.com/pub/epel/9/Everything/x86_64"
+  mirrorlist = [
+    "https://mirror-a.example.net/epel/9/Everything/x86_64",
+    "https://mirror-b.example.org/epel/9/Everything/x86_64",
+  ]
+  mirror_strategy = "least_conn"
+}
+```
+
+## Example
+
+See `examples/resources/artifactapi_remote_deb/main.tf`.

docs/resources/remote_docker.md

@@ -0,0 +1,52 @@
+# `artifactapi_remote_docker`
+
+Per-type remote resources manage upstream repository proxies. Each type applies its own mutability classification rules automatically (e.g., Docker classifies tag manifests as mutable and blobs as immutable; Helm classifies `index.yaml` as mutable).
+
+## Common Attributes
+
+| Attribute            | Required | Default | Description                                                       |
+|----------------------|----------|---------|-------------------------------------------------------------------|
+| `name`               | Yes      |         | Unique name (forces replacement on change)                        |
+| `base_url`           | Yes      |         | Upstream repository URL                                           |
+| `description`        | No       | `""`    | Human-readable description                                        |
+| `username`           | No       | `""`    | Upstream auth username (sensitive)                                 |
+| `password`           | No       | `""`    | Upstream auth password (sensitive)                                 |
+| `immutable_ttl`      | No       | `0`     | TTL in seconds for immutable artifacts (0 = cache forever)        |
+| `mutable_ttl`        | No       | `3600`  | TTL in seconds for mutable artifacts                              |
+| `check_mutable`      | No       | `true`  | Enable conditional revalidation for mutable artifacts             |
+| `patterns`           | No       |         | Allowlist of path patterns to proxy (empty = all)                 |
+| `blocklist`          | No       |         | Paths to always deny (checked before patterns)                    |
+| `mutable_patterns`   | No       |         | Override: treat matching paths as mutable                         |
+| `immutable_patterns` | No       |         | Override: treat matching paths as immutable                       |
+| `quarantine_enabled` | No       | `false` | Enable quarantine for new artifacts                               |
+| `quarantine_days`    | No       | `3`     | Days to quarantine new artifacts                                  |
+| `stale_on_error`     | No       | `true`  | Serve stale cache when upstream is unreachable                    |
+| `upstream_dial_timeout` | No    | `0`     | Upstream TCP connect timeout in seconds (0 = server default)      |
+| `upstream_tls_timeout` | No     | `0`     | Upstream TLS handshake timeout in seconds (0 = server default)    |
+| `upstream_response_header_timeout` | No | `0` | Upstream response-header timeout in seconds (0 = server default) |
+
+## Docker-specific Attributes
+
+| Attribute          | Default | Description                |
+|--------------------|---------|----------------------------|
+| `ban_tags_enabled` | `false` | Enable tag banning         |
+| `ban_tags`         |         | List of tags to ban        |
+
+## Example
+
+```hcl
+resource "artifactapi_remote_docker" "dockerhub" {
+  name     = "dockerhub"
+  base_url = "https://registry-1.docker.io"
+
+  immutable_ttl    = 0
+  mutable_ttl      = 300
+  ban_tags_enabled = true
+  ban_tags         = ["latest"]
+
+  patterns = [
+    "^library/postgres",
+    "^library/redis",
+  ]
+}
+```

docs/resources/remote_gems.md

@@ -0,0 +1,30 @@
+# `artifactapi_remote_gems`
+
+Per-type remote resources manage upstream repository proxies. Each type applies its own mutability classification rules automatically (e.g., Docker classifies tag manifests as mutable and blobs as immutable; Helm classifies `index.yaml` as mutable).
+
+## Common Attributes
+
+| Attribute            | Required | Default | Description                                                       |
+|----------------------|----------|---------|-------------------------------------------------------------------|
+| `name`               | Yes      |         | Unique name (forces replacement on change)                        |
+| `base_url`           | Yes      |         | Upstream repository URL                                           |
+| `description`        | No       | `""`    | Human-readable description                                        |
+| `username`           | No       | `""`    | Upstream auth username (sensitive)                                 |
+| `password`           | No       | `""`    | Upstream auth password (sensitive)                                 |
+| `immutable_ttl`      | No       | `0`     | TTL in seconds for immutable artifacts (0 = cache forever)        |
+| `mutable_ttl`        | No       | `3600`  | TTL in seconds for mutable artifacts                              |
+| `check_mutable`      | No       | `true`  | Enable conditional revalidation for mutable artifacts             |
+| `patterns`           | No       |         | Allowlist of path patterns to proxy (empty = all)                 |
+| `blocklist`          | No       |         | Paths to always deny (checked before patterns)                    |
+| `mutable_patterns`   | No       |         | Override: treat matching paths as mutable                         |
+| `immutable_patterns` | No       |         | Override: treat matching paths as immutable                       |
+| `quarantine_enabled` | No       | `false` | Enable quarantine for new artifacts                               |
+| `quarantine_days`    | No       | `3`     | Days to quarantine new artifacts                                  |
+| `stale_on_error`     | No       | `true`  | Serve stale cache when upstream is unreachable                    |
+| `upstream_dial_timeout` | No    | `0`     | Upstream TCP connect timeout in seconds (0 = server default)      |
+| `upstream_tls_timeout` | No     | `0`     | Upstream TLS handshake timeout in seconds (0 = server default)    |
+| `upstream_response_header_timeout` | No | `0` | Upstream response-header timeout in seconds (0 = server default) |
+
+## Example
+
+See `examples/resources/artifactapi_remote_gems/main.tf`.

docs/resources/remote_generic.md

@@ -0,0 +1,30 @@
+# `artifactapi_remote_generic`
+
+Per-type remote resources manage upstream repository proxies. Each type applies its own mutability classification rules automatically (e.g., Docker classifies tag manifests as mutable and blobs as immutable; Helm classifies `index.yaml` as mutable).
+
+## Common Attributes
+
+| Attribute            | Required | Default | Description                                                       |
+|----------------------|----------|---------|-------------------------------------------------------------------|
+| `name`               | Yes      |         | Unique name (forces replacement on change)                        |
+| `base_url`           | Yes      |         | Upstream repository URL                                           |
+| `description`        | No       | `""`    | Human-readable description                                        |
+| `username`           | No       | `""`    | Upstream auth username (sensitive)                                 |
+| `password`           | No       | `""`    | Upstream auth password (sensitive)                                 |
+| `immutable_ttl`      | No       | `0`     | TTL in seconds for immutable artifacts (0 = cache forever)        |
+| `mutable_ttl`        | No       | `3600`  | TTL in seconds for mutable artifacts                              |
+| `check_mutable`      | No       | `true`  | Enable conditional revalidation for mutable artifacts             |
+| `patterns`           | No       |         | Allowlist of path patterns to proxy (empty = all)                 |
+| `blocklist`          | No       |         | Paths to always deny (checked before patterns)                    |
+| `mutable_patterns`   | No       |         | Override: treat matching paths as mutable                         |
+| `immutable_patterns` | No       |         | Override: treat matching paths as immutable                       |
+| `quarantine_enabled` | No       | `false` | Enable quarantine for new artifacts                               |
+| `quarantine_days`    | No       | `3`     | Days to quarantine new artifacts                                  |
+| `stale_on_error`     | No       | `true`  | Serve stale cache when upstream is unreachable                    |
+| `upstream_dial_timeout` | No    | `0`     | Upstream TCP connect timeout in seconds (0 = server default)      |
+| `upstream_tls_timeout` | No     | `0`     | Upstream TLS handshake timeout in seconds (0 = server default)    |
+| `upstream_response_header_timeout` | No | `0` | Upstream response-header timeout in seconds (0 = server default) |
+
+## Example
+
+See `examples/resources/artifactapi_remote_generic/main.tf`.

docs/resources/remote_github_alpine.md

@@ -0,0 +1,49 @@
+# `artifactapi_remote_github_alpine`
+
+Per-type remote resources manage upstream repository proxies. Each type applies its own mutability classification rules automatically (e.g., Docker classifies tag manifests as mutable and blobs as immutable; Helm classifies `index.yaml` as mutable).
+
+## Common Attributes
+
+| Attribute            | Required | Default | Description                                                       |
+|----------------------|----------|---------|-------------------------------------------------------------------|
+| `name`               | Yes      |         | Unique name (forces replacement on change)                        |
+| `base_url`           | Yes      |         | Upstream repository URL                                           |
+| `description`        | No       | `""`    | Human-readable description                                        |
+| `username`           | No       | `""`    | Upstream auth username (sensitive)                                 |
+| `password`           | No       | `""`    | Upstream auth password (sensitive)                                 |
+| `immutable_ttl`      | No       | `0`     | TTL in seconds for immutable artifacts (0 = cache forever)        |
+| `mutable_ttl`        | No       | `3600`  | TTL in seconds for mutable artifacts                              |
+| `check_mutable`      | No       | `true`  | Enable conditional revalidation for mutable artifacts             |
+| `patterns`           | No       |         | Allowlist of path patterns to proxy (empty = all)                 |
+| `blocklist`          | No       |         | Paths to always deny (checked before patterns)                    |
+| `mutable_patterns`   | No       |         | Override: treat matching paths as mutable                         |
+| `immutable_patterns` | No       |         | Override: treat matching paths as immutable                       |
+| `quarantine_enabled` | No       | `false` | Enable quarantine for new artifacts                               |
+| `quarantine_days`    | No       | `3`     | Days to quarantine new artifacts                                  |
+| `stale_on_error`     | No       | `true`  | Serve stale cache when upstream is unreachable                    |
+| `upstream_dial_timeout` | No    | `0`     | Upstream TCP connect timeout in seconds (0 = server default)      |
+| `upstream_tls_timeout` | No     | `0`     | Upstream TLS handshake timeout in seconds (0 = server default)    |
+| `upstream_response_header_timeout` | No | `0` | Upstream response-header timeout in seconds (0 = server default) |
+
+## Terraform / github_rpm / github_deb / github_alpine-specific Attributes
+
+| Attribute         | Default | Description                                              |
+|-------------------|---------|----------------------------------------------------------|
+| `releases_remote` | `""`   | Name of a backend remote that serves the download bytes. Terraform uses it for download URL rewriting; `github_rpm`/`github_deb`/`github_alpine` 302-redirect `.rpm`/`.deb`/`.apk` downloads to it. |
+
+## Notes
+
+`artifactapi_remote_github_alpine` is the Alpine/apk analog of `github_rpm`: it
+exposes a GitHub repo's release `.apk` assets as an `apk` repository, synthesizing
+the apk index (`APKINDEX.tar.gz`) from release metadata without precaching
+packages. Set `base_url` to the releases API root
+(`https://api.github.com/repos/{owner}/{repo}`) and `releases_remote` to a
+generic `github.com` remote that streams the `.apk` bytes; `.apk` downloads
+302-redirect there. `patterns` filters which release assets become packages
+(regex on asset filename). `password` may hold a token for private repos or
+higher API rate limits. See
+`examples/resources/artifactapi_remote_github_alpine/main.tf`.
+
+## Example
+
+See `examples/resources/artifactapi_remote_github_alpine/main.tf`.

docs/resources/remote_github_deb.md

@@ -0,0 +1,49 @@
+# `artifactapi_remote_github_deb`
+
+Per-type remote resources manage upstream repository proxies. Each type applies its own mutability classification rules automatically (e.g., Docker classifies tag manifests as mutable and blobs as immutable; Helm classifies `index.yaml` as mutable).
+
+## Common Attributes
+
+| Attribute            | Required | Default | Description                                                       |
+|----------------------|----------|---------|-------------------------------------------------------------------|
+| `name`               | Yes      |         | Unique name (forces replacement on change)                        |
+| `base_url`           | Yes      |         | Upstream repository URL                                           |
+| `description`        | No       | `""`    | Human-readable description                                        |
+| `username`           | No       | `""`    | Upstream auth username (sensitive)                                 |
+| `password`           | No       | `""`    | Upstream auth password (sensitive)                                 |
+| `immutable_ttl`      | No       | `0`     | TTL in seconds for immutable artifacts (0 = cache forever)        |
+| `mutable_ttl`        | No       | `3600`  | TTL in seconds for mutable artifacts                              |
+| `check_mutable`      | No       | `true`  | Enable conditional revalidation for mutable artifacts             |
+| `patterns`           | No       |         | Allowlist of path patterns to proxy (empty = all)                 |
+| `blocklist`          | No       |         | Paths to always deny (checked before patterns)                    |
+| `mutable_patterns`   | No       |         | Override: treat matching paths as mutable                         |
+| `immutable_patterns` | No       |         | Override: treat matching paths as immutable                       |
+| `quarantine_enabled` | No       | `false` | Enable quarantine for new artifacts                               |
+| `quarantine_days`    | No       | `3`     | Days to quarantine new artifacts                                  |
+| `stale_on_error`     | No       | `true`  | Serve stale cache when upstream is unreachable                    |
+| `upstream_dial_timeout` | No    | `0`     | Upstream TCP connect timeout in seconds (0 = server default)      |
+| `upstream_tls_timeout` | No     | `0`     | Upstream TLS handshake timeout in seconds (0 = server default)    |
+| `upstream_response_header_timeout` | No | `0` | Upstream response-header timeout in seconds (0 = server default) |
+
+## Terraform / github_rpm / github_deb / github_alpine-specific Attributes
+
+| Attribute         | Default | Description                                              |
+|-------------------|---------|----------------------------------------------------------|
+| `releases_remote` | `""`   | Name of a backend remote that serves the download bytes. Terraform uses it for download URL rewriting; `github_rpm`/`github_deb`/`github_alpine` 302-redirect `.rpm`/`.deb`/`.apk` downloads to it. |
+
+## Notes
+
+`artifactapi_remote_github_deb` is the Debian/apt analog of `github_rpm`: it
+exposes a GitHub repo's release `.deb` assets as an `apt` repository, synthesizing
+the apt index (`Packages`/`Release`) from release metadata without precaching
+packages. Set `base_url` to the releases API root
+(`https://api.github.com/repos/{owner}/{repo}`) and `releases_remote` to a
+generic `github.com` remote that streams the `.deb` bytes; `.deb` downloads
+302-redirect there. `patterns` filters which release assets become packages
+(regex on asset filename). `password` may hold a token for private repos or
+higher API rate limits. See
+`examples/resources/artifactapi_remote_github_deb/main.tf`.
+
+## Example
+
+See `examples/resources/artifactapi_remote_github_deb/main.tf`.

docs/resources/remote_github_rpm.md

@@ -0,0 +1,46 @@
+# `artifactapi_remote_github_rpm`
+
+Per-type remote resources manage upstream repository proxies. Each type applies its own mutability classification rules automatically (e.g., Docker classifies tag manifests as mutable and blobs as immutable; Helm classifies `index.yaml` as mutable).
+
+## Common Attributes
+
+| Attribute            | Required | Default | Description                                                       |
+|----------------------|----------|---------|-------------------------------------------------------------------|
+| `name`               | Yes      |         | Unique name (forces replacement on change)                        |
+| `base_url`           | Yes      |         | Upstream repository URL                                           |
+| `description`        | No       | `""`    | Human-readable description                                        |
+| `username`           | No       | `""`    | Upstream auth username (sensitive)                                 |
+| `password`           | No       | `""`    | Upstream auth password (sensitive)                                 |
+| `immutable_ttl`      | No       | `0`     | TTL in seconds for immutable artifacts (0 = cache forever)        |
+| `mutable_ttl`        | No       | `3600`  | TTL in seconds for mutable artifacts                              |
+| `check_mutable`      | No       | `true`  | Enable conditional revalidation for mutable artifacts             |
+| `patterns`           | No       |         | Allowlist of path patterns to proxy (empty = all)                 |
+| `blocklist`          | No       |         | Paths to always deny (checked before patterns)                    |
+| `mutable_patterns`   | No       |         | Override: treat matching paths as mutable                         |
+| `immutable_patterns` | No       |         | Override: treat matching paths as immutable                       |
+| `quarantine_enabled` | No       | `false` | Enable quarantine for new artifacts                               |
+| `quarantine_days`    | No       | `3`     | Days to quarantine new artifacts                                  |
+| `stale_on_error`     | No       | `true`  | Serve stale cache when upstream is unreachable                    |
+| `upstream_dial_timeout` | No    | `0`     | Upstream TCP connect timeout in seconds (0 = server default)      |
+| `upstream_tls_timeout` | No     | `0`     | Upstream TLS handshake timeout in seconds (0 = server default)    |
+| `upstream_response_header_timeout` | No | `0` | Upstream response-header timeout in seconds (0 = server default) |
+
+## Terraform / github_rpm / github_deb / github_alpine-specific Attributes
+
+| Attribute         | Default | Description                                              |
+|-------------------|---------|----------------------------------------------------------|
+| `releases_remote` | `""`   | Name of a backend remote that serves the download bytes. Terraform uses it for download URL rewriting; `github_rpm`/`github_deb`/`github_alpine` 302-redirect `.rpm`/`.deb`/`.apk` downloads to it. |
+
+## Notes
+
+`artifactapi_remote_github_rpm` exposes a GitHub repo's releases as a `dnf`/`yum`
+repository without precaching packages. Set `base_url` to the releases API root
+(`https://api.github.com/repos/{owner}/{repo}`) and `releases_remote` to a
+generic `github.com` remote that streams the `.rpm` bytes. `patterns` filters
+which release assets become packages (regex on asset filename). `password` may
+hold a token for private repos or higher API rate limits. See
+`examples/resources/artifactapi_remote_github_rpm/main.tf`.
+
+## Example
+
+See `examples/resources/artifactapi_remote_github_rpm/main.tf`.

docs/resources/remote_goproxy.md

@@ -0,0 +1,30 @@
+# `artifactapi_remote_goproxy`
+
+Per-type remote resources manage upstream repository proxies. Each type applies its own mutability classification rules automatically (e.g., Docker classifies tag manifests as mutable and blobs as immutable; Helm classifies `index.yaml` as mutable).
+
+## Common Attributes
+
+| Attribute            | Required | Default | Description                                                       |
+|----------------------|----------|---------|-------------------------------------------------------------------|
+| `name`               | Yes      |         | Unique name (forces replacement on change)                        |
+| `base_url`           | Yes      |         | Upstream repository URL                                           |
+| `description`        | No       | `""`    | Human-readable description                                        |
+| `username`           | No       | `""`    | Upstream auth username (sensitive)                                 |
+| `password`           | No       | `""`    | Upstream auth password (sensitive)                                 |
+| `immutable_ttl`      | No       | `0`     | TTL in seconds for immutable artifacts (0 = cache forever)        |
+| `mutable_ttl`        | No       | `3600`  | TTL in seconds for mutable artifacts                              |
+| `check_mutable`      | No       | `true`  | Enable conditional revalidation for mutable artifacts             |
+| `patterns`           | No       |         | Allowlist of path patterns to proxy (empty = all)                 |
+| `blocklist`          | No       |         | Paths to always deny (checked before patterns)                    |
+| `mutable_patterns`   | No       |         | Override: treat matching paths as mutable                         |
+| `immutable_patterns` | No       |         | Override: treat matching paths as immutable                       |
+| `quarantine_enabled` | No       | `false` | Enable quarantine for new artifacts                               |
+| `quarantine_days`    | No       | `3`     | Days to quarantine new artifacts                                  |
+| `stale_on_error`     | No       | `true`  | Serve stale cache when upstream is unreachable                    |
+| `upstream_dial_timeout` | No    | `0`     | Upstream TCP connect timeout in seconds (0 = server default)      |
+| `upstream_tls_timeout` | No     | `0`     | Upstream TLS handshake timeout in seconds (0 = server default)    |
+| `upstream_response_header_timeout` | No | `0` | Upstream response-header timeout in seconds (0 = server default) |
+
+## Example
+
+See `examples/resources/artifactapi_remote_goproxy/main.tf`.

docs/resources/remote_helm.md

@@ -0,0 +1,30 @@
+# `artifactapi_remote_helm`
+
+Per-type remote resources manage upstream repository proxies. Each type applies its own mutability classification rules automatically (e.g., Docker classifies tag manifests as mutable and blobs as immutable; Helm classifies `index.yaml` as mutable).
+
+## Common Attributes
+
+| Attribute            | Required | Default | Description                                                       |
+|----------------------|----------|---------|-------------------------------------------------------------------|
+| `name`               | Yes      |         | Unique name (forces replacement on change)                        |
+| `base_url`           | Yes      |         | Upstream repository URL                                           |
+| `description`        | No       | `""`    | Human-readable description                                        |
+| `username`           | No       | `""`    | Upstream auth username (sensitive)                                 |
+| `password`           | No       | `""`    | Upstream auth password (sensitive)                                 |
+| `immutable_ttl`      | No       | `0`     | TTL in seconds for immutable artifacts (0 = cache forever)        |
+| `mutable_ttl`        | No       | `3600`  | TTL in seconds for mutable artifacts                              |
+| `check_mutable`      | No       | `true`  | Enable conditional revalidation for mutable artifacts             |
+| `patterns`           | No       |         | Allowlist of path patterns to proxy (empty = all)                 |
+| `blocklist`          | No       |         | Paths to always deny (checked before patterns)                    |
+| `mutable_patterns`   | No       |         | Override: treat matching paths as mutable                         |
+| `immutable_patterns` | No       |         | Override: treat matching paths as immutable                       |
+| `quarantine_enabled` | No       | `false` | Enable quarantine for new artifacts                               |
+| `quarantine_days`    | No       | `3`     | Days to quarantine new artifacts                                  |
+| `stale_on_error`     | No       | `true`  | Serve stale cache when upstream is unreachable                    |
+| `upstream_dial_timeout` | No    | `0`     | Upstream TCP connect timeout in seconds (0 = server default)      |
+| `upstream_tls_timeout` | No     | `0`     | Upstream TLS handshake timeout in seconds (0 = server default)    |
+| `upstream_response_header_timeout` | No | `0` | Upstream response-header timeout in seconds (0 = server default) |
+
+## Example
+
+See `examples/resources/artifactapi_remote_helm/main.tf`.

docs/resources/remote_npm.md

@@ -0,0 +1,30 @@
+# `artifactapi_remote_npm`
+
+Per-type remote resources manage upstream repository proxies. Each type applies its own mutability classification rules automatically (e.g., Docker classifies tag manifests as mutable and blobs as immutable; Helm classifies `index.yaml` as mutable).
+
+## Common Attributes
+
+| Attribute            | Required | Default | Description                                                       |
+|----------------------|----------|---------|-------------------------------------------------------------------|
+| `name`               | Yes      |         | Unique name (forces replacement on change)                        |
+| `base_url`           | Yes      |         | Upstream repository URL                                           |
+| `description`        | No       | `""`    | Human-readable description                                        |
+| `username`           | No       | `""`    | Upstream auth username (sensitive)                                 |
+| `password`           | No       | `""`    | Upstream auth password (sensitive)                                 |
+| `immutable_ttl`      | No       | `0`     | TTL in seconds for immutable artifacts (0 = cache forever)        |
+| `mutable_ttl`        | No       | `3600`  | TTL in seconds for mutable artifacts                              |
+| `check_mutable`      | No       | `true`  | Enable conditional revalidation for mutable artifacts             |
+| `patterns`           | No       |         | Allowlist of path patterns to proxy (empty = all)                 |
+| `blocklist`          | No       |         | Paths to always deny (checked before patterns)                    |
+| `mutable_patterns`   | No       |         | Override: treat matching paths as mutable                         |
+| `immutable_patterns` | No       |         | Override: treat matching paths as immutable                       |
+| `quarantine_enabled` | No       | `false` | Enable quarantine for new artifacts                               |
+| `quarantine_days`    | No       | `3`     | Days to quarantine new artifacts                                  |
+| `stale_on_error`     | No       | `true`  | Serve stale cache when upstream is unreachable                    |
+| `upstream_dial_timeout` | No    | `0`     | Upstream TCP connect timeout in seconds (0 = server default)      |
+| `upstream_tls_timeout` | No     | `0`     | Upstream TLS handshake timeout in seconds (0 = server default)    |
+| `upstream_response_header_timeout` | No | `0` | Upstream response-header timeout in seconds (0 = server default) |
+
+## Example
+
+See `examples/resources/artifactapi_remote_npm/main.tf`.

docs/resources/remote_puppet.md

@@ -0,0 +1,30 @@
+# `artifactapi_remote_puppet`
+
+Per-type remote resources manage upstream repository proxies. Each type applies its own mutability classification rules automatically (e.g., Docker classifies tag manifests as mutable and blobs as immutable; Helm classifies `index.yaml` as mutable).
+
+## Common Attributes
+
+| Attribute            | Required | Default | Description                                                       |
+|----------------------|----------|---------|-------------------------------------------------------------------|
+| `name`               | Yes      |         | Unique name (forces replacement on change)                        |
+| `base_url`           | Yes      |         | Upstream repository URL                                           |
+| `description`        | No       | `""`    | Human-readable description                                        |
+| `username`           | No       | `""`    | Upstream auth username (sensitive)                                 |
+| `password`           | No       | `""`    | Upstream auth password (sensitive)                                 |
+| `immutable_ttl`      | No       | `0`     | TTL in seconds for immutable artifacts (0 = cache forever)        |
+| `mutable_ttl`        | No       | `3600`  | TTL in seconds for mutable artifacts                              |
+| `check_mutable`      | No       | `true`  | Enable conditional revalidation for mutable artifacts             |
+| `patterns`           | No       |         | Allowlist of path patterns to proxy (empty = all)                 |
+| `blocklist`          | No       |         | Paths to always deny (checked before patterns)                    |
+| `mutable_patterns`   | No       |         | Override: treat matching paths as mutable                         |
+| `immutable_patterns` | No       |         | Override: treat matching paths as immutable                       |
+| `quarantine_enabled` | No       | `false` | Enable quarantine for new artifacts                               |
+| `quarantine_days`    | No       | `3`     | Days to quarantine new artifacts                                  |
+| `stale_on_error`     | No       | `true`  | Serve stale cache when upstream is unreachable                    |
+| `upstream_dial_timeout` | No    | `0`     | Upstream TCP connect timeout in seconds (0 = server default)      |
+| `upstream_tls_timeout` | No     | `0`     | Upstream TLS handshake timeout in seconds (0 = server default)    |
+| `upstream_response_header_timeout` | No | `0` | Upstream response-header timeout in seconds (0 = server default) |
+
+## Example
+
+See `examples/resources/artifactapi_remote_puppet/main.tf`.

docs/resources/remote_pypi.md

@@ -0,0 +1,30 @@
+# `artifactapi_remote_pypi`
+
+Per-type remote resources manage upstream repository proxies. Each type applies its own mutability classification rules automatically (e.g., Docker classifies tag manifests as mutable and blobs as immutable; Helm classifies `index.yaml` as mutable).
+
+## Common Attributes
+
+| Attribute            | Required | Default | Description                                                       |
+|----------------------|----------|---------|-------------------------------------------------------------------|
+| `name`               | Yes      |         | Unique name (forces replacement on change)                        |
+| `base_url`           | Yes      |         | Upstream repository URL                                           |
+| `description`        | No       | `""`    | Human-readable description                                        |
+| `username`           | No       | `""`    | Upstream auth username (sensitive)                                 |
+| `password`           | No       | `""`    | Upstream auth password (sensitive)                                 |
+| `immutable_ttl`      | No       | `0`     | TTL in seconds for immutable artifacts (0 = cache forever)        |
+| `mutable_ttl`        | No       | `3600`  | TTL in seconds for mutable artifacts                              |
+| `check_mutable`      | No       | `true`  | Enable conditional revalidation for mutable artifacts             |
+| `patterns`           | No       |         | Allowlist of path patterns to proxy (empty = all)                 |
+| `blocklist`          | No       |         | Paths to always deny (checked before patterns)                    |
+| `mutable_patterns`   | No       |         | Override: treat matching paths as mutable                         |
+| `immutable_patterns` | No       |         | Override: treat matching paths as immutable                       |
+| `quarantine_enabled` | No       | `false` | Enable quarantine for new artifacts                               |
+| `quarantine_days`    | No       | `3`     | Days to quarantine new artifacts                                  |
+| `stale_on_error`     | No       | `true`  | Serve stale cache when upstream is unreachable                    |
+| `upstream_dial_timeout` | No    | `0`     | Upstream TCP connect timeout in seconds (0 = server default)      |
+| `upstream_tls_timeout` | No     | `0`     | Upstream TLS handshake timeout in seconds (0 = server default)    |
+| `upstream_response_header_timeout` | No | `0` | Upstream response-header timeout in seconds (0 = server default) |
+
+## Example
+
+See `examples/resources/artifactapi_remote_pypi/main.tf`.

docs/resources/remote_rpm.md

@@ -0,0 +1,53 @@
+# `artifactapi_remote_rpm`
+
+Per-type remote resources manage upstream repository proxies. Each type applies its own mutability classification rules automatically (e.g., Docker classifies tag manifests as mutable and blobs as immutable; Helm classifies `index.yaml` as mutable).
+
+## Common Attributes
+
+| Attribute            | Required | Default | Description                                                       |
+|----------------------|----------|---------|-------------------------------------------------------------------|
+| `name`               | Yes      |         | Unique name (forces replacement on change)                        |
+| `base_url`           | Yes      |         | Upstream repository URL                                           |
+| `description`        | No       | `""`    | Human-readable description                                        |
+| `username`           | No       | `""`    | Upstream auth username (sensitive)                                 |
+| `password`           | No       | `""`    | Upstream auth password (sensitive)                                 |
+| `immutable_ttl`      | No       | `0`     | TTL in seconds for immutable artifacts (0 = cache forever)        |
+| `mutable_ttl`        | No       | `3600`  | TTL in seconds for mutable artifacts                              |
+| `check_mutable`      | No       | `true`  | Enable conditional revalidation for mutable artifacts             |
+| `patterns`           | No       |         | Allowlist of path patterns to proxy (empty = all)                 |
+| `blocklist`          | No       |         | Paths to always deny (checked before patterns)                    |
+| `mutable_patterns`   | No       |         | Override: treat matching paths as mutable                         |
+| `immutable_patterns` | No       |         | Override: treat matching paths as immutable                       |
+| `quarantine_enabled` | No       | `false` | Enable quarantine for new artifacts                               |
+| `quarantine_days`    | No       | `3`     | Days to quarantine new artifacts                                  |
+| `stale_on_error`     | No       | `true`  | Serve stale cache when upstream is unreachable                    |
+| `upstream_dial_timeout` | No    | `0`     | Upstream TCP connect timeout in seconds (0 = server default)      |
+| `upstream_tls_timeout` | No     | `0`     | Upstream TLS handshake timeout in seconds (0 = server default)    |
+| `upstream_response_header_timeout` | No | `0` | Upstream response-header timeout in seconds (0 = server default) |
+
+## rpm / deb / alpine-specific Attributes
+
+| Attribute         | Default       | Description                                                                                     |
+|-------------------|---------------|-------------------------------------------------------------------------------------------------|
+| `mirrorlist`      |               | Extra upstream mirror base URLs. Requests are load-balanced with failover across `base_url` + `mirrorlist`. |
+| `mirror_strategy` | `round_robin` | Mirror load-balancing strategy across `base_url` + `mirrorlist`. One of `round_robin` or `least_conn`. |
+
+Only valid on the `artifactapi_remote_rpm`, `artifactapi_remote_deb`, and
+`artifactapi_remote_alpine` resources. Setting either on any other remote type is
+rejected at plan time.
+
+```hcl
+resource "artifactapi_remote_rpm" "epel" {
+  name     = "epel-9"
+  base_url = "https://download.example.com/pub/epel/9/Everything/x86_64"
+  mirrorlist = [
+    "https://mirror-a.example.net/epel/9/Everything/x86_64",
+    "https://mirror-b.example.org/epel/9/Everything/x86_64",
+  ]
+  mirror_strategy = "least_conn"
+}
+```
+
+## Example
+
+See `examples/resources/artifactapi_remote_rpm/main.tf`.

docs/resources/remote_terraform.md

@@ -0,0 +1,36 @@
+# `artifactapi_remote_terraform`
+
+Per-type remote resources manage upstream repository proxies. Each type applies its own mutability classification rules automatically (e.g., Docker classifies tag manifests as mutable and blobs as immutable; Helm classifies `index.yaml` as mutable).
+
+## Common Attributes
+
+| Attribute            | Required | Default | Description                                                       |
+|----------------------|----------|---------|-------------------------------------------------------------------|
+| `name`               | Yes      |         | Unique name (forces replacement on change)                        |
+| `base_url`           | Yes      |         | Upstream repository URL                                           |
+| `description`        | No       | `""`    | Human-readable description                                        |
+| `username`           | No       | `""`    | Upstream auth username (sensitive)                                 |
+| `password`           | No       | `""`    | Upstream auth password (sensitive)                                 |
+| `immutable_ttl`      | No       | `0`     | TTL in seconds for immutable artifacts (0 = cache forever)        |
+| `mutable_ttl`        | No       | `3600`  | TTL in seconds for mutable artifacts                              |
+| `check_mutable`      | No       | `true`  | Enable conditional revalidation for mutable artifacts             |
+| `patterns`           | No       |         | Allowlist of path patterns to proxy (empty = all)                 |
+| `blocklist`          | No       |         | Paths to always deny (checked before patterns)                    |
+| `mutable_patterns`   | No       |         | Override: treat matching paths as mutable                         |
+| `immutable_patterns` | No       |         | Override: treat matching paths as immutable                       |
+| `quarantine_enabled` | No       | `false` | Enable quarantine for new artifacts                               |
+| `quarantine_days`    | No       | `3`     | Days to quarantine new artifacts                                  |
+| `stale_on_error`     | No       | `true`  | Serve stale cache when upstream is unreachable                    |
+| `upstream_dial_timeout` | No    | `0`     | Upstream TCP connect timeout in seconds (0 = server default)      |
+| `upstream_tls_timeout` | No     | `0`     | Upstream TLS handshake timeout in seconds (0 = server default)    |
+| `upstream_response_header_timeout` | No | `0` | Upstream response-header timeout in seconds (0 = server default) |
+
+## Terraform / github_rpm / github_deb / github_alpine-specific Attributes
+
+| Attribute         | Default | Description                                              |
+|-------------------|---------|----------------------------------------------------------|
+| `releases_remote` | `""`   | Name of a backend remote that serves the download bytes. Terraform uses it for download URL rewriting; `github_rpm`/`github_deb`/`github_alpine` 302-redirect `.rpm`/`.deb`/`.apk` downloads to it. |
+
+## Example
+
+See `examples/resources/artifactapi_remote_terraform/main.tf`.

docs/resources/virtual.md

@@ -0,0 +1,23 @@
+# `artifactapi_virtual`
+
+Virtual repositories merge multiple remotes of the same package type into a single endpoint.
+
+```hcl
+resource "artifactapi_virtual" "helm" {
+  name         = "helm"
+  package_type = "helm"
+  description  = "All helm repos merged"
+
+  members = [
+    artifactapi_remote_helm.jetstack.name,
+    artifactapi_remote_helm.hashicorp_helm.name,
+  ]
+}
+```
+
+| Attribute      | Required | Description                               |
+|----------------|----------|-------------------------------------------|
+| `name`         | Yes      | Unique name (forces replacement on change)|
+| `package_type` | Yes      | Package type of member remotes            |
+| `description`  | No       | Human-readable description                |
+| `members`      | Yes      | List of remote names to include           |