diff --git a/pkg/agent/delivery/factory.go b/pkg/agent/delivery/factory.go
index 4c9e5c051..6a2040bda 100644
--- a/pkg/agent/delivery/factory.go
+++ b/pkg/agent/delivery/factory.go
@@ -28,6 +28,9 @@ func NewAgentDelivery(opts FactoryOptions) AgentDelivery {
 	switch {
 	case driverType == provider.CustomDriver:
 		log.Debugf("using legacy shell delivery for custom driver")
+		log.Warnf(
+			"legacy shell delivery is deprecated; platform-native delivery will replace this in a future release",
+		)
 		return &LegacyShellDelivery{
 			ExecFunc:    opts.ExecFunc,
 			DownloadURL: "",
@@ -35,6 +38,9 @@ func NewAgentDelivery(opts FactoryOptions) AgentDelivery {
 
 	case driverType == provider.KubernetesDriver:
 		log.Debugf("using legacy shell delivery for kubernetes driver")
+		log.Warnf(
+			"legacy shell delivery is deprecated; platform-native delivery will replace this in a future release",
+		)
 		return &LegacyShellDelivery{
 			ExecFunc:    opts.ExecFunc,
 			DownloadURL: "",
@@ -66,6 +72,9 @@ func NewAgentDelivery(opts FactoryOptions) AgentDelivery {
 
 	default:
 		log.Debugf("using legacy shell delivery for driver: %s", driverType)
+		log.Warnf(
+			"legacy shell delivery is deprecated; platform-native delivery will replace this in a future release",
+		)
 		return &LegacyShellDelivery{
 			ExecFunc:    opts.ExecFunc,
 			DownloadURL: "",
diff --git a/pkg/agent/delivery/legacy_shell.go b/pkg/agent/delivery/legacy_shell.go
index 5b74eece0..795d66066 100644
--- a/pkg/agent/delivery/legacy_shell.go
+++ b/pkg/agent/delivery/legacy_shell.go
@@ -10,20 +10,25 @@ import (
 	"github.com/devsy-org/devsy/pkg/log"
 )
 
+// Deprecated: LegacyShellDelivery is deprecated. Platform-native AgentDelivery implementations
+// (LocalDockerDelivery, RemoteDockerDelivery, KubernetesDelivery) are the replacements.
 type LegacyShellDelivery struct {
 	ExecFunc    inject.ExecFunc
 	DownloadURL string
 	Timeout     func() *agent.InjectOptions
 }
 
+// Deprecated: Phase is part of LegacyShellDelivery which is deprecated.
 func (d *LegacyShellDelivery) Phase() DeliveryPhase {
 	return PhasePostStart
 }
 
+// Deprecated: DeliverPreStart is part of LegacyShellDelivery which is deprecated.
 func (d *LegacyShellDelivery) DeliverPreStart(_ context.Context, _ PreStartOptions) error {
 	return fmt.Errorf("LegacyShellDelivery does not support pre-start delivery")
 }
 
+// Deprecated: DeliverPostStart is part of LegacyShellDelivery which is deprecated.
 func (d *LegacyShellDelivery) DeliverPostStart(ctx context.Context, opts PostStartOptions) error {
 	if d.ExecFunc == nil {
 		return fmt.Errorf("exec function is required for legacy shell delivery")
@@ -53,6 +58,7 @@ func (d *LegacyShellDelivery) DeliverPostStart(ctx context.Context, opts PostSta
 	return nil
 }
 
+// Deprecated: Cleanup is part of LegacyShellDelivery which is deprecated.
 func (d *LegacyShellDelivery) Cleanup(_ context.Context, _ string) error {
 	return nil
 }
@@ -67,6 +73,9 @@ func (d *LegacyShellDelivery) downloadURL() string {
 // ExecFuncFromDriver creates an inject.ExecFunc that routes commands through
 // the provided driver command function. This adapts the driver's
 // CommandDevContainer signature for use with the legacy injection path.
+//
+// Deprecated: Platform-native AgentDelivery implementations
+// (LocalDockerDelivery, RemoteDockerDelivery, KubernetesDelivery) are the replacements.
 func ExecFuncFromDriver(
 	cmdFn func(ctx context.Context, user, command string, stdin io.Reader, stdout io.Writer, stderr io.Writer) error,
 	user string,
diff --git a/pkg/inject/inject.go b/pkg/inject/inject.go
index 43575ef0a..6493608a4 100644
--- a/pkg/inject/inject.go
+++ b/pkg/inject/inject.go
@@ -16,11 +16,18 @@ import (
 	"github.com/devsy-org/devsy/pkg/log"
 )
 
+// Deprecated: Script embeds inject.sh which is deprecated. Platform-native AgentDelivery
+// implementations (LocalDockerDelivery, RemoteDockerDelivery, KubernetesDelivery) are the replacements.
+//
 //go:embed inject.sh
 var Script string
 
+// Deprecated: ExecFunc is part of the legacy shell injection path. Platform-native AgentDelivery
+// implementations (LocalDockerDelivery, RemoteDockerDelivery, KubernetesDelivery) are the replacements.
 type ExecFunc func(ctx context.Context, command string, stdin io.Reader, stdout io.Writer, stderr io.Writer) error
 
+// Deprecated: LocalFile is part of the legacy shell injection path. Platform-native AgentDelivery
+// implementations (LocalDockerDelivery, RemoteDockerDelivery, KubernetesDelivery) are the replacements.
 type LocalFile func(arm bool) (io.ReadCloser, error)
 
 type injectResult struct {
@@ -28,6 +35,8 @@ type injectResult struct {
 	err         error
 }
 
+// Deprecated: InjectOptions is part of the legacy shell injection path. Platform-native AgentDelivery
+// implementations (LocalDockerDelivery, RemoteDockerDelivery, KubernetesDelivery) are the replacements.
 type InjectOptions struct {
 	Ctx          context.Context
 	Exec         ExecFunc
@@ -39,6 +48,8 @@ type InjectOptions struct {
 	Timeout      time.Duration
 }
 
+// Deprecated: Inject is part of the legacy shell injection path. Platform-native AgentDelivery
+// implementations (LocalDockerDelivery, RemoteDockerDelivery, KubernetesDelivery) are the replacements.
 func Inject(opts InjectOptions) (bool, error) {
 	if opts.Ctx == nil {
 		return false, fmt.Errorf("context is required")
diff --git a/pkg/inject/inject.sh b/pkg/inject/inject.sh
index 8326efe14..b94f6d995 100644
--- a/pkg/inject/inject.sh
+++ b/pkg/inject/inject.sh
@@ -1,4 +1,6 @@
 #!/bin/sh
+# Deprecated: inject.sh is deprecated. Platform-native AgentDelivery implementations
+# (LocalDockerDelivery, RemoteDockerDelivery, KubernetesDelivery) are the replacements.
 set -e
 
 INSTALL_DIR="{{ .InstallDir }}"