Decide: stance on documented-but-dead VisioScripting methods

[saveenr]

Open sub-question carved out of #156's closing comment. Decision-only; must be answered before #131 starts the gitbook write-up.

Background

The hybrid public-API decision in #156 committed VisioScripting.Client and the 25-group facade as the public-stable contract. The pre-decision usage audit found ~36 public methods on the *Commands classes with zero external callers (no cmdlet, no test, no sample, no doc snippet). Phase A removal of those methods is deferred to CY27 in #183, which means the methods will be present in the documented surface during CY26Q3–CY26Q4.

#131 is the doc-write that turns this surface into gitbook pages. Before it starts, we need to know how to characterize the dead methods on their pages.

The two options

Option A — "public, documented, candidate for CY27 removal"

• Each dead method gets a normal gitbook page in the standard ## Syntax / ## Parameters / ## Examples / ## See also layout.
• A "Remarks" section flags removal candidacy: e.g. "This method has no known consumers and is a candidate for removal in CY27. See #183."
• Honest with consumers; gives advance notice; aligned with the project's "improve before audience-reducing changes" guiding principle.
• Some doc work in #131 is partially-throwaway (the dead-method pages will likely be deleted in CY27).

Option B — "public, documented, stable"

• Each dead method gets a normal gitbook page, no removal hint.
• Simpler to write; no precedent for "candidate" markings on the gitbook.
• If a CY27 removal happens, it's a bigger surprise and a harder deprecation story.
• A reader can't distinguish "actually used by cmdlets" from "no known consumer" — every method looks equally load-bearing.

Acceptance

• Decision recorded as a comment on this issue + reflected in the #156 ADR (docs/decisions/visioscripting-public-api.md, landing as part of #182 Phase C).
• #131 cross-referenced so the doc-writer knows the stance before starting per-page templates.

Effort

S — decision only.

See also

• #156 — hybrid public-API decision and the audit findings that surfaced this question.
• #182 — pre-lock cleanup (CY26Q3); its Phase C lands the ADR that should record whichever answer this issue produces.
• #183 — CY27 dead-method removal (Phase A); the eventual destination either way.
• #131 — the doc-write whose template choice depends on this answer.

[saveenr]

Decision: Option A

Documented-but-dead methods on the Client / *Commands public surface will be marked in their gitbook pages as candidates for CY27 removal.

Each affected method's page on the gitbook gets a "Remarks" section (or equivalent) noting:

Remarks: This method has no known consumers as of 2026-05 and is a candidate for removal in CY27. See #183.

The list of methods that get this flag is the ~36 identified in the #156 usage audit (filed under "Dead methods" in #183's body).

Rationale

The strongest argument for A over B (no signal) is alignment with the audit's transparency. The audit found, with high confidence, that these methods have zero callers. Erasing that information in the public docs creates a parallel doc-vs-code reality where every method page looks equally load-bearing even though some of them are concretely on a sunset path. Telling the reader honestly distinguishes "well-trodden API the project actively maintains" from "exists for completeness, may go away." That helps anyone choosing between two ways to do something pick the one with momentum.

The cost of A (some doc work is partially-throwaway when CY27 deletion happens, plus a small risk of self-fulfilling prophecy) is real but acceptable. The deprecation cycle is graceful: the gitbook flags the candidacy now, the codebase strengthens to [Obsolete("Will be removed in version X")] near deletion, the gitbook page updates again to reflect that, and finally the page is removed when the method is. The "Remarks" wording makes the candidacy advisory rather than a hard deprecation, which leaves room to walk the flag back if usage develops between now and CY27.

Implications

• #131 per-group page template carries a "Remarks" section that's populated only for the dead methods in that group. The doc-writer references the #183 list as the source of truth for which methods get the flag.
• docs/decisions/visioscripting-public-api.md updated in this same change-set to record this resolution (the ADR previously noted this as an open sub-question pointing at this issue).
• #183 when it executes should remove both the methods and the corresponding gitbook pages and Remarks blocks. The instructions on #183 already include the doc-cleanup; this decision adds: also remove the per-method "Remarks: candidate for CY27 removal" blocks now that the candidacy resolved into deletion.

Closing.