[Docs] Clarify overlay visibility semantics

README.md

@@ -283,6 +283,11 @@ commands:
         default: viewer
 ```
 
+Command `ignore: true` removes a generated command. Command `hidden: true`
+keeps it generated but hidden from normal help and catalog output unless
+`--include-hidden` is used. Parameter `hidden: true` is a legacy alias for
+`deprecated: true`; prefer `deprecated: true` for parameter overlays.
+
 Run codegen with an overlay directory:
 
 ```sh

docs/architecture.md

@@ -214,10 +214,12 @@ Overlays apply at codegen-time. The runtime has no overlay types. This matrix sh
 | `Required` | `required` / path rule | relaxation only (post-v0.1) | overlay > spec |
 | `Default` | spec or overlay | value | overlay > spec |
 | `Enum`, `Format` | spec | override (post-v0.1) | overlay > spec |
-| `Deprecated` | `param.deprecated` | bool | overlay > spec |
+| `Deprecated` | `param.deprecated` | bool; `param.hidden` is a legacy alias | overlay > spec |
 
 Two restricted-override rules: **`Required`** may only relax (required → optional), never tighten. **`GoType`** may only narrow (e.g. `string` → typed enum), never widen.
 
+Command `ignore` drops an operation during codegen, so it is absent from the generated CLI and catalog. Command `hidden` keeps the operation generated but hides it from normal help, search, and catalog output; `--include-hidden` can still inspect it. Parameter `hidden` does not hide a flag; it is retained only as a legacy spelling for `deprecated: true`. Prefer `deprecated: true` for parameter overlays.
+
 ## Runtime request lifecycle
 
 ```mermaid

internal/codegen/render/render.go

@@ -102,7 +102,7 @@ func MergeOverlay(specs []runtime.CommandSpec, overrides map[string]overlay.Over
 				if po.Default != "" {
 					cs.Params[j].Default = po.Default
 				}
-				if po.Deprecated || po.Hidden {
+				if po.Deprecated || po.DeprecatedAlias {
 					cs.Params[j].Deprecated = true
 				}
 			}

internal/codegen/render/render_test.go

@@ -143,13 +143,15 @@ func TestRenderModule_ParamOverride(t *testing.T) {
 			Group: "Users", Use: "list-users", Short: "list", Method: "GET", PathTpl: "/users",
 			Params: []runtime.ParamSpec{
 				{Name: "status", Flag: "status", In: "query", GoType: "string", Help: "original help"},
+				{Name: "legacy", Flag: "legacy", In: "query", GoType: "string", Help: "legacy help"},
 			},
 		},
 	}
 	overrides := map[string]overlay.Override{
 		"list-users": {
 			Params: map[string]overlay.ParamOverride{
-				"status": {Flag: "user-status", Help: "override help", Default: "active"},
+				"status": {Flag: "user-status", Help: "override help", Default: "active", Deprecated: true},
+				"legacy": {DeprecatedAlias: true},
 			},
 		},
 	}
@@ -173,6 +175,9 @@ func TestRenderModule_ParamOverride(t *testing.T) {
 	if strings.Contains(got, `"original help"`) {
 		t.Error("original help should not appear")
 	}
+	if strings.Count(got, `Deprecated: true`) != 2 {
+		t.Errorf("deprecated and legacy hidden alias should both mark params deprecated; output:\n%s", got)
+	}
 }
 
 func TestRenderModule_NilOverrides(t *testing.T) {

internal/overlay/overlay.go

@@ -24,11 +24,11 @@ type Override struct {
 }
 
 type ParamOverride struct {
-	Flag       string `yaml:"flag"`
-	Help       string `yaml:"help"`
-	Default    string `yaml:"default"`
-	Hidden     bool   `yaml:"hidden"`
-	Deprecated bool   `yaml:"deprecated"`
+	Flag            string `yaml:"flag"`
+	Help            string `yaml:"help"`
+	Default         string `yaml:"default"`
+	DeprecatedAlias bool   `yaml:"hidden"`
+	Deprecated      bool   `yaml:"deprecated"`
 }
 
 type KnownError struct {

internal/overlay/overlay_test.go

@@ -79,6 +79,8 @@ func TestLoadDir_ParsesExtendedFields(t *testing.T) {
         help: "Account status"
         default: "active"
         deprecated: true
+      legacy:
+        hidden: true
   delete-user:
     ignore: true
   get-user:
@@ -117,6 +119,10 @@ func TestLoadDir_ParsesExtendedFields(t *testing.T) {
 	if !sp.Deprecated {
 		t.Error("param deprecated = false, want true")
 	}
+	lp := cu.Params["legacy"]
+	if !lp.DeprecatedAlias {
+		t.Error("legacy param hidden alias = false, want true")
+	}
 	du := got["iam"]["delete-user"]
 	if !du.Ignore {
 		t.Error("delete-user ignore = false, want true")