From 0e38db9442480d7d63edf42647a4f0a62f32e15c Mon Sep 17 00:00:00 2001
From: Ilyaas Kapadia <86218345+IlyaasK@users.noreply.github.com>
Date: Sat, 11 Jul 2026 05:09:25 -0400
Subject: [PATCH] Document extension upload and import

Add a Terraform 1.11-compatible extension example that tracks exact archive bytes with filesha256, publish the same snippet and import forms in generated Registry docs, and update the example index. This gives users a validated durable upload workflow without bundling a binary archive.
---
 docs/resources/extension.md                   | 32 +++++++++++++++++++
 examples/README.md                            |  3 +-
 examples/extension/main.tf                    | 22 +++++++++++++
 examples/resources/kernel_extension/import.sh |  6 ++++
 .../resources/kernel_extension/resource.tf    | 14 ++++++++
 5 files changed, 76 insertions(+), 1 deletion(-)
 create mode 100644 examples/extension/main.tf
 create mode 100644 examples/resources/kernel_extension/import.sh
 create mode 100644 examples/resources/kernel_extension/resource.tf

diff --git a/docs/resources/extension.md b/docs/resources/extension.md
index a5711c6..0efe977 100644
--- a/docs/resources/extension.md
+++ b/docs/resources/extension.md
@@ -10,7 +10,24 @@ description: |-
 
 Kernel uploaded extension durable configuration.
 
+## Example Usage
 
+```terraform
+terraform {
+  required_version = ">= 1.11.0"
+}
+
+variable "extension_zip_path" {
+  type        = string
+  description = "Path to a Chrome extension ZIP with a Manifest V3 manifest."
+}
+
+resource "kernel_extension" "example" {
+  name          = "productivity-tools"
+  source_path   = var.extension_zip_path
+  source_sha256 = filesha256(var.extension_zip_path)
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema
@@ -27,3 +44,18 @@ Kernel uploaded extension durable configuration.
 ### Read-Only
 
 - `id` (String) Unique extension identifier.
+
+## Import
+
+Import is supported using the following syntax:
+
+The [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import) can be used, for example:
+
+```shell
+# The bare form resolves the project like create: the provider default,
+# else the API key's binding.
+terraform import kernel_extension.example <extension-id>
+
+# The project-qualified form imports an extension from a specific project.
+terraform import kernel_extension.example <project-id>/<extension-id>
+```
diff --git a/examples/README.md b/examples/README.md
index ebd6116..49badd6 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -2,7 +2,7 @@
 
 These examples show durable Terraform configuration only.
 
-They do not acquire browsers, release browsers, invoke apps, fetch logs, take screenshots, open live view, upload extensions, or force-delete active runtime state.
+They do not acquire browsers, release browsers, invoke apps, fetch logs, take screenshots, open live view, download extensions, or force-delete active runtime state.
 
 Set the API credential before running Terraform:
 
@@ -22,6 +22,7 @@ Use local development overrides while the provider is unreleased. See the root [
 
 - [basic-browser-pool](basic-browser-pool) creates a minimal durable browser pool.
 - [design-preview-browser-pool](design-preview-browser-pool) shows a browser pool shaped for repeated design-preview checks without modeling the browser sessions themselves.
+- [extension](extension) uploads an immutable extension archive and tracks exact content changes with `filesha256`.
 - [lookups](lookups) shows read-only project, profile, proxy, and extension data sources.
 - [project](project) creates a durable Kernel project with an explicit unique name.
 - [project-scoped-browser-pool](project-scoped-browser-pool) places a browser pool in an explicit project, overriding the provider-level `project_id` default.
diff --git a/examples/extension/main.tf b/examples/extension/main.tf
new file mode 100644
index 0000000..c38a1f7
--- /dev/null
+++ b/examples/extension/main.tf
@@ -0,0 +1,22 @@
+terraform {
+  required_version = ">= 1.11.0"
+
+  required_providers {
+    kernel = {
+      source = "kernel/kernel"
+    }
+  }
+}
+
+provider "kernel" {}
+
+variable "extension_zip_path" {
+  type        = string
+  description = "Path to a Chrome extension ZIP with a Manifest V3 manifest."
+}
+
+resource "kernel_extension" "example" {
+  name          = "productivity-tools"
+  source_path   = var.extension_zip_path
+  source_sha256 = filesha256(var.extension_zip_path)
+}
diff --git a/examples/resources/kernel_extension/import.sh b/examples/resources/kernel_extension/import.sh
new file mode 100644
index 0000000..b86e5d7
--- /dev/null
+++ b/examples/resources/kernel_extension/import.sh
@@ -0,0 +1,6 @@
+# The bare form resolves the project like create: the provider default,
+# else the API key's binding.
+terraform import kernel_extension.example <extension-id>
+
+# The project-qualified form imports an extension from a specific project.
+terraform import kernel_extension.example <project-id>/<extension-id>
diff --git a/examples/resources/kernel_extension/resource.tf b/examples/resources/kernel_extension/resource.tf
new file mode 100644
index 0000000..c0a56c3
--- /dev/null
+++ b/examples/resources/kernel_extension/resource.tf
@@ -0,0 +1,14 @@
+terraform {
+  required_version = ">= 1.11.0"
+}
+
+variable "extension_zip_path" {
+  type        = string
+  description = "Path to a Chrome extension ZIP with a Manifest V3 manifest."
+}
+
+resource "kernel_extension" "example" {
+  name          = "productivity-tools"
+  source_path   = var.extension_zip_path
+  source_sha256 = filesha256(var.extension_zip_path)
+}