diff --git a/cmd/gen-services/internal/generator/generator.go b/cmd/gen-services/internal/generator/generator.go
index ac7512c5..b7b716ef 100644
--- a/cmd/gen-services/internal/generator/generator.go
+++ b/cmd/gen-services/internal/generator/generator.go
@@ -120,6 +120,11 @@ func generateAPIReference(controllers []types.Controller, path string) error {
 
 		for _, crd := range c.CRDs {
 			if r := parseCRD(crd.Content, c.ServiceName); r != nil {
+				if c.Documentation != nil {
+					if resCfg, ok := c.Documentation.Resources[r.Kind]; ok && resCfg.Note != nil {
+						r.Note = strings.TrimRight(*resCfg.Note, "\n")
+					}
+				}
 				serviceMap[c.ServiceName] = append(serviceMap[c.ServiceName], *r)
 			}
 		}
diff --git a/cmd/gen-services/internal/scanner/scanner.go b/cmd/gen-services/internal/scanner/scanner.go
index 54f28acf..0d27dcc9 100644
--- a/cmd/gen-services/internal/scanner/scanner.go
+++ b/cmd/gen-services/internal/scanner/scanner.go
@@ -83,14 +83,16 @@ func scanOne(path, service string) (*types.Controller, error) {
 	}
 
 	examples, _ := collectExamples(path) // non-fatal if missing
+	docCfg, _ := readDocumentationConfig(path) // non-fatal if missing
 
 	return &types.Controller{
-		ServiceName: service,
-		Path:        path,
-		Metadata:    metadata,
-		Version:     version,
-		CRDs:        crds,
-		Examples:    examples,
+		ServiceName:   service,
+		Path:          path,
+		Metadata:      metadata,
+		Version:       version,
+		CRDs:          crds,
+		Examples:      examples,
+		Documentation: docCfg,
 	}, nil
 }
 
@@ -186,6 +188,18 @@ func collectExamples(controllerPath string) ([]types.ExampleFile, error) {
 	return examples, nil
 }
 
+func readDocumentationConfig(controllerPath string) (*types.DocumentationConfig, error) {
+	data, err := os.ReadFile(filepath.Join(controllerPath, "documentation.yaml"))
+	if err != nil {
+		return nil, err
+	}
+	var cfg types.DocumentationConfig
+	if err := yaml.Unmarshal(data, &cfg); err != nil {
+		return nil, err
+	}
+	return &cfg, nil
+}
+
 func extractKind(content []byte) string {
 	var r struct {
 		Kind string `yaml:"kind"`
diff --git a/cmd/gen-services/internal/types/types.go b/cmd/gen-services/internal/types/types.go
index 2e2355da..4925a2e5 100644
--- a/cmd/gen-services/internal/types/types.go
+++ b/cmd/gen-services/internal/types/types.go
@@ -15,12 +15,23 @@ package types
 
 // Controller holds data collected from scanning a single controller repo.
 type Controller struct {
-	ServiceName string
-	Path        string
-	Metadata    *Metadata
-	Version     string
-	CRDs        []CRDFile
-	Examples    []ExampleFile
+	ServiceName    string
+	Path           string
+	Metadata       *Metadata
+	Version        string
+	CRDs           []CRDFile
+	Examples       []ExampleFile
+	Documentation  *DocumentationConfig
+}
+
+// DocumentationConfig mirrors the documentation.yaml in controller repos.
+type DocumentationConfig struct {
+	Resources map[string]*ResourceDocsConfig `yaml:"resources"`
+}
+
+// ResourceDocsConfig holds resource-level documentation overrides.
+type ResourceDocsConfig struct {
+	Note *string `yaml:"note"`
 }
 
 // Metadata mirrors the metadata.yaml in controller repos.
@@ -96,6 +107,7 @@ type Resource struct {
 	Version      string  `json:"version"`
 	Scope        string  `json:"scope"`
 	Description  string  `json:"description,omitempty"`
+	Note         string  `json:"note,omitempty"`
 	Path         string  `json:"path"`
 	SpecFields   []Field `json:"specFields"`
 	StatusFields []Field `json:"statusFields"`
diff --git a/website/src/pages/api-reference.module.css b/website/src/pages/api-reference.module.css
index 6dec4459..08bf2833 100644
--- a/website/src/pages/api-reference.module.css
+++ b/website/src/pages/api-reference.module.css
@@ -381,6 +381,38 @@
   color: var(--ifm-color-emphasis-800);
 }
 
+/* Resource Note */
+.resourceNote {
+  margin: 1.5rem 0;
+  padding: 1.25rem;
+  background: linear-gradient(135deg, rgba(59, 130, 246, 0.06) 0%, rgba(59, 130, 246, 0.02) 100%);
+  border-left: 4px solid #3b82f6;
+  border-radius: 6px;
+  line-height: 1.6;
+}
+
+[data-theme='dark'] .resourceNote {
+  background: linear-gradient(135deg, rgba(96, 165, 250, 0.08) 0%, rgba(96, 165, 250, 0.03) 100%);
+  border-left-color: #60a5fa;
+}
+
+.resourceNoteHeader {
+  font-size: 0.8rem;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  color: #3b82f6;
+  margin-bottom: 0.5rem;
+}
+
+[data-theme='dark'] .resourceNoteHeader {
+  color: #60a5fa;
+}
+
+.resourceNoteBody {
+  color: var(--ifm-color-emphasis-800);
+}
+
 /* Sections */
 .section {
   margin-bottom: 2.5rem;
diff --git a/website/src/pages/api-reference.tsx b/website/src/pages/api-reference.tsx
index 005ffb5b..6dd48ec3 100644
--- a/website/src/pages/api-reference.tsx
+++ b/website/src/pages/api-reference.tsx
@@ -24,6 +24,7 @@ interface ResourceEntry {
   version: string;
   scope: string;
   description?: string;
+  note?: string;
   path: string;
   specFields: Field[];
   statusFields: Field[];
@@ -322,6 +323,15 @@ function ResourceDetail({ resource, serviceName, onBack, onHome }: { resource: R
         </div>
       )}
 
+      {resource.note && (
+        <div className={styles.resourceNote}>
+          <div className={styles.resourceNoteHeader}>Note</div>
+          <div className={styles.resourceNoteBody}>
+            <DescriptionMarkdown text={resource.note} />
+          </div>
+        </div>
+      )}
+
       <FieldTable fields={resource.specFields} title="Spec Fields" />
       <FieldTable fields={resource.statusFields} title="Status Fields" />
     </div>