chore: update readme

Signed-off-by: Alano Terblanche <18033717+Benehiko@users.noreply.github.com>

Author: Benehiko

NOTICE

@@ -0,0 +1,19 @@
+Docker
+Copyright 2012-2026 Docker, Inc.
+
+This product includes software developed at Docker, Inc. (https://www.docker.com).
+
+This product contains software (https://github.com/keybase/go-keychain) developed
+by Keybase, licensed under the MIT License.
+
+The following is courtesy of our legal counsel:
+
+
+Use and transfer of Docker may be subject to certain restrictions by the
+United States and other governments.
+It is your responsibility to ensure that your use and/or transfer does not
+violate applicable laws.
+
+For more information, see https://www.bis.doc.gov
+
+See also https://www.apache.org/dev/crypto.html and/or seek legal counsel.

README.md

@@ -4,21 +4,97 @@
 [![lint](https://github.com/docker/secrets-engine/actions/workflows/lint.yml/badge.svg?branch=main)](https://github.com/docker/secrets-engine/actions/workflows/lint.yml)
 [![License](https://img.shields.io/badge/license-Apache%202.0-purple)](https://github.com/docker/secrets-engine/blob/main/LICENSE)
 
-## Quickstart
+Secrets Engine and [docker pass](https://docs.docker.com/reference/cli/docker/pass/)
+are bundled with [Docker Desktop](https://docs.docker.com/desktop/).
+A standalone version can also be installed from the [releases](https://github.com/docker/secrets-engine/releases).
 
-Secrets Engine and [docker pass](https://docs.docker.com/reference/cli/docker/pass/) are bundled with [Docker Desktop](https://docs.docker.com/desktop/).
+> [!NOTE]
+> Secret injection in Docker CE is on our roadmap.
 
-Let's store a secret using `docker pass` in the OS Keychain and then inject it
-into a running container using Secrets Engine.
+## Runtime secret injection (no plaintext in your CLI or Compose)
 
-```console
-# Store `Foo` in the OS Keychain
-$ docker pass set Foo=bar
-# Tell docker to use the Secrets Engine using the `se://` URI on an environment variable
-$ docker run --rm -e Foo=se://Foo busybox /bin/sh -c "echo \${Foo}"
-$ bar
+Secrets Engine lets you **reference** secrets in `docker run` / `docker compose`
+and have Docker **resolve and inject** the real values _at runtime_.
+
+**Key idea:** you pass a _pointer_, not the secret.
+
+- In your config (CLI flags / Compose files), you use a `se://` reference like `se://foo`.
+- When the container starts, Docker asks Secrets Engine to resolve that reference
+  and injects the secret into the container.
+- The secret value is sourced from a provider, such as **`docker pass`**, which
+  stores secrets securely in your **local OS keychain** (or from a custom provider plugin).
+
+This means you don’t need:
+
+- host environment variables containing secret values
+- plaintext secret files on disk
+- secret literals embedded in `compose.yaml`
+
+### Example: store once, use everywhere
+
+Store the secret in your OS keychain:
+
+```bash
+docker pass set foo=bar
+```
+
+Run a container using a secret reference (the value se://foo is not the secret itself):
+
+```bash
+docker run --rm -e foo=se://foo busybox sh -c 'echo "$foo"'
+```
+
+Compose example:
+
+```yaml
+services:
+  app:
+    image: your/image
+    environment:
+      API_TOKEN: se://foo
 ```
 
+### Realms (namespace + pattern matching)
+
+Secrets Engine supports **realms**: a simple namespacing scheme that helps you
+organize secrets by purpose, environment, or target system, and then retrieve
+them using glob-style patterns.
+
+A realm is just a prefix in the secret key. For example:
+
+- `docker/auth/hub/mysecret`
+- `docker/auth/ghcr/token`
+- `docker/db/prod/password`
+
+Because the realm is part of the key, you can query or operate on groups of
+secrets using patterns. For example, to target _all_ Docker auth-related secrets:
+
+- `docker/auth/**`
+
+This makes it easy to:
+
+- keep related secrets grouped together
+- separate environments (e.g. `prod/`, `staging/`, `dev/`)
+- scope listing/lookup operations to a subset of secrets without knowing every
+  key ahead of time
+
+#### Example layout
+
+```text
+docker/
+  auth/
+    hub/
+      mysecret
+    ghcr/
+      token
+  db/
+    prod/
+      password
+```
+
+> [!TIP]
+> Treat realms like paths - predictable structure makes automation and access control much easier.
+
 # Developer Guides
 
 ## How to query secrets
@@ -38,11 +114,16 @@ if err != nil {
 }
 
 // Fetch a secret from the engine
-resp, err := c.GetSecrets(t.Context(), client.MustParsePattern("my-secret"))
+// We are using an exact match here, so only one or zero results will return.
+secrets, err := c.GetSecrets(t.Context(), client.MustParsePattern("my-secret"))
 if err != nil {
     log.Fatalf("failed fetching secrets: %v", err)
 }
-fmt.Println(resp.Value)
+// Since we used an exact match, only one secret should be present.
+if len(secrets) == 0 {
+    log.Fatalf("hmm... seems like the plugin isn't returning an ErrNotFound")
+}
+fmt.Println(secrets[0].Value)
 ```
 
 ## How to create a plugin
@@ -62,17 +143,17 @@ var _ plugin.Plugin = &myPlugin{}
 
 type myPlugin struct {
 	m      sync.Mutex
-	secrets map[secrets.ID]string
+	secrets map[plugin.ID]string
 }
 
-func (p *myPlugin) GetSecret(_ context.Context, request secrets.Request) ([]secrets.Envelope, error) {
+func (p *myPlugin) GetSecrets(_ context.Context, pattern plugin.Pattern) ([]plugin.Envelope, error) {
 	p.m.Lock()
 	defer p.m.Unlock()
 
-	var result []secrets.Envelope
+	var result []plugin.Envelope
 	for id, value := range p.secrets {
-		if request.Pattern.Match(id) {
-			result = append(result, secrets.Envelope{
+		if pattern.Match(id) {
+			result = append(result, plugin.Envelope{
 				ID:    id,
 				Value: []byte(value),
 				CreatedAt: time.Now(),
@@ -82,11 +163,11 @@ func (p *myPlugin) GetSecret(_ context.Context, request secrets.Request) ([]secr
 	return result, nil
 }
 
-func (p *myPlugin) Config() plugin.Config {
-	return plugin.Config{
-		Version: "v0.0.1",
-		Pattern: "*",
-	}
+func (p *myPlugin) Run(ctx context.Context) error {
+    // add long-running tasks here
+    // for example, OAuth tokens can be refreshed here.
+	<-ctx.Done()
+	return nil
 }
 ```
 
@@ -99,32 +180,89 @@ package main
 
 import (
 	"context"
+	"log/slog"
 
 	"github.com/docker/secrets-engine/plugin"
 )
 
+type myLogger struct{}
+
+func (m *myLogger) Errorf(format string, v ...any) {
+	slog.Error(fmt.Sprintf(format, v...))
+}
+
+func (m *myLogger) Printf(format string, v ...any) {
+	slog.Info(fmt.Sprintf(format, v...))
+}
+
+func (m *myLogger) Warnf(format string, v ...any) {
+	slog.Warn(fmt.Sprintf(format, v...))
+}
+
 func main() {
-    p, err := plugin.New(&myPlugin{secrets: map[secrets.ID]string{"foo": "bar"}})
-    if err != nil {
-        panic(err)
-    }
-	// Run your plugin
-    if err := p.Run(context.Background()); err != nil {
-        panic(err)
+    config := plugin.Config{
+		Version: plugin.MustNewVersion("v0.0.1"),
+		Pattern: plugin.MustParsePattern("myrealm/**"),
+        // custom logger
+		Logger:  &myLogger{},
+	}
+    secrets := map[plugin.ID]string{
+        plugin.MustParseID("myrealm/foo"): "bar",
     }
+	p, err := plugin.New(&myPlugin{secrets: secrets}, config)
+	if err != nil {
+		panic(err)
+	}
+    // Run your plugin
+	if err := p.Run(context.Background()); err != nil {
+		panic(err)
+	}
 }
 ```
 
-### 3. Test and verify the plugin:
+### 3. Query secrets from your plugin:
 
 The secrets engine is integrated with Docker Desktop.
 To verify your plugin works, run the binary.
 Using the SDK it will automatically connect to the secrets engine in Docker Desktop.
 Then, you can query secrets, e.g. using curl:
 
-```console
-$ curl --unix-socket ~/Library/Caches/docker-secrets-engine/engine.sock \
+```bash
+curl --unix-socket ~/Library/Caches/docker-secrets-engine/daemon.sock \
     -X POST http://localhost/resolver.v1.ResolverService/GetSecrets \
-    -H "Content-Type: application/json" -d '{"pattern": "foo"}'
-{"id":"foo","value":"bar","provider":"docker-pass","version":"","error":"","createdAt":"0001-01-01T00:00:00Z","resolvedAt":"2025-08-12T08:25:06.166714Z","expiresAt":"0001-01-01T00:00:00Z"}
+    -H "Content-Type: application/json" \
+    -d '{"pattern": "myrealm/**"}'
 ```
+
+> [!NOTE]
+> Querying Secrets Engine installed with Docker Desktop requires a different
+> socket: `~/Library/Caches/docker-secrets-engine/engine.sock`
+
+The value of a secret is always encoded into base64.
+When using Go's `json.Unmarshal` it will automatically convert it back into
+a slice of bytes `[]byte`.
+
+To manually decode it, you can pipe the value into `base64 --decode -i`.
+
+```bash
+echo "<base64 string>" | base64 --decode -i
+```
+
+## Legal
+
+_Brought to you courtesy of our legal counsel. For more context,
+see the [NOTICE](https://github.com/docker/secrets-engine/blob/main/NOTICE) document in this repo._
+
+Use and transfer of Docker may be subject to certain restrictions by the
+United States and other governments.
+
+It is your responsibility to ensure that your use and/or transfer does not
+violate applicable laws.
+
+For more information, see https://www.bis.doc.gov
+
+## Licensing
+
+docker/secrets-engine is licensed under the Apache License, Version 2.0. See
+[LICENSE](https://github.com/docker/secrets-engine/blob/main/LICENSE) for the full
+license text.