platty-docs-target-curation

name	platty-docs-target-curation
description	Use when listing, filtering, including, deprecating, or reviewing Platty technical documentation targets before docs generation.

Platty Docs Target Curation

Analytics Attribution

For direct invocation, set PLATTY_INVOCATION_SOURCE=platty-docs-target-curation on every Platty CLI process in this workflow. If an outer user-facing workflow routes here, the outer workflow label wins and overrides this default. Preserve the active label for retries, resumes, and every nextCommand or nextAction.command execution.

PLATTY_INVOCATION_SOURCE=platty-docs-target-curation platty targets list --project <project> --json

Use this before technical document generation when the user wants to inspect or narrow API, screen, event, or job targets.

Flow

Run curation as ordered steps, not ad-hoc commands:

1. List and narrow the candidate targets:

platty targets list --project <project> --json
platty targets list --project <project> --kind api --status active --json

Use --kind, --repo, --method, --status, --search, --limit, and --offset to narrow large target sets.

2. Exclude bad or out-of-scope targets:

platty targets deprecate --project <project> --ids <bad-id1,bad-id2> --note "<reason>" --json

3. Lock the accepted scope by explicitly including the accepted target ids. include is not only an undo for deprecate — it records the accepted curation decision:

platty targets include --project <project> --ids <accepted-id1,accepted-id2> --json

4. Re-list with the same filters and confirm only the accepted targets remain active.

5. Rebuild and review shared segments before generation so cross-target shared code is grouped:

Advanced compatibility commands:

platty docs shared-segments rebuild --project <project> --json
platty docs shared-segments list --project <project> --json

Advanced compatibility note: platty docs targets ... remains available for existing automation, but public guidance should use top-level platty targets.

Stop Conditions

• deprecate / include fails with TARGET_NOT_FOUND or TARGET_SELECTOR_AMBIGUOUS: stop mutating scope — re-run targets list and use exact ids from the fresh listing. If an id from the fresh listing still fails, report it instead of guessing.
• targets list returns zero targets while platty status reports build_docs: stop curation — static analysis has not produced targets for this project; go back to platty-static-analysis and report.
• The step-4 re-list does not reflect a mutation you just made (a deprecated id is still active, or an included id is missing): stop and report — do not re-issue the same deprecate/include in a loop.

Next Step

Switch to platty-generated-docs after target scope is accepted.

Handoff

End curation with the Platty handoff card. The State line must include the accepted/included target count or the exact reason no targets are available. The Recommended next line should be:

Recommended next: platty-generated-docs with platty generate-docs run --project <project> --json