No deprecation lifecycle exists anywhere — stock FieldOptions.deprecated unused, and structured data already in the schema doesn't reach the surfaces that need it

Researched how a deprecation would actually surface today across CLI/LSP/MCP/docs. Short answer: it wouldn't, and several small, already-half-built mechanisms would close most of the gap without needing an option ceremony.

• Zero use of protobuf's own [deprecated = true] FieldOptions anywhere in the schema (grep confirms). This is a stock descriptorpb field, not a custom extension — fd.Options().GetDeprecated() is free to read via protoreflect, and could feed a "(deprecated)" badge in docs/reference/*.md, a flow validate diagnostic, and a deprecated marker on the corresponding MCP tool-schema property, all from the exact same read.
• pflag.Flag.Deprecated is likewise a first-class field cobra already supports — cmd/flow/suggest.go already reads f.Deprecated when ranking did-you-mean suggestions, but grep MarkDeprecated across the repo (excluding tests) returns zero calls. The check is live and has nothing to check.
• InputDeclaration.example (flowstate.proto#L685) is real, structured, author-validated data — a typed Value literal checked by CheckInputExample and already rendered by LSP hover. It never reaches TaskField (flowstate.proto#L3127-L3158, no example field) or Catalog()'s TaskField construction, so docs/reference/tasks.md and the MCP tool description both miss a worked example that's one hop away and already validated.
• flow fix's retiredTasks map (fixretire.go#L38-L42) holds real migration knowledge (which names were retired, how to rewrite them) that's invisible outside this one file — flow validate's "unknown task" diagnostic for a retired name could name the retirement and point at flow fix instead of reading as a plain typo.

Note: docs/DSL.md's "No deprecation window" is a considered, stated position for the DSL itself (task/keyword spellings retire via rewriter, not a deprecated-but-working window) — this issue isn't proposing to reopen that. It's scoped to the surfaces that already do keep old things alive for compatibility (proto fields across editions, RPCs, CLI flags), where nothing today signals "still works, going away" at all.

Fix, in mechanical-first order:

1. Start calling .MarkDeprecated() and setting [deprecated = true] where something is actually being phased out — zero new mechanism, the readers already exist or are trivial.
2. Wire InputDeclaration.example through to TaskField and render it in docs/reference/tasks.md and MCP tool descriptions.
3. Export retiredTasks' key set so flow validate's diagnostic can name a retirement specifically.
4. Only if reason/replacement/version text is wanted beyond the on/off bit: a small FieldOptions/MethodOptions extension (FlowstateDeprecation{reason, replacement, since}), which the schema's own CELFunction.example precedent already establishes as the right shape when reflection genuinely can't carry the fact.

Start with cmd/flow/suggest.go, the schema locations in proto/flowstate/v1/flowstate.proto, and pkg/flowstate/v1/flowfile/fixretire.go. Trace how deprecation flags, InputDeclaration.example, and retiredTasks currently flow into validation, docs, LSP, and MCP surfaces. Done means the selected metadata is surfaced consistently and the retired-task diagnostic identifies the migration path.