Add [MANUAL] notation for steps requiring human interaction

[jpoehnelt]

Problem

Since gws is optimized for AI agents, there is no clear signal when a command or setup step requires manual human interaction (e.g. opening a browser, clicking through a UI). AI agents need to know when to hand control back to the user.

Proposal

Add a [MANUAL] notation to help text and error hints for steps that cannot be automated via the CLI.

Phase 1: Help text and error hints

Add [MANUAL] prefix to non-automatable steps in --help and runtime error messages:

SETUP REQUIREMENTS:
  1. Auth with cloud-platform scope: gws auth login
  2. [MANUAL] Link the script to your OAuth client's GCP project:
     Open the script editor → Project Settings → Change GCP project
  3. Add to appsscript.json: "executionApi": {"access": "MYSELF"}

Phase 2: Structured JSON errors (optional)

For --format json, include a machine-readable hint object:

{
  "error": { "code": 403, "message": "..." },
  "hint": {
    "manual_action_required": true,
    "steps": ["Link script to GCP project in the script editor"],
    "automatable_steps": ["gws auth login", "update appsscript.json"]
  }
}

Affected commands

Command	Manual step
gws auth login	Browser-based OAuth consent flow
apps-script +open	Opens browser (by design)
apps-script +run	GCP project linking requires script editor UI
gws auth setup	Downloading OAuth client JSON from GCP console

Design considerations

• Notation should be parseable by both humans and AI agents
• [MANUAL] is simple, grep-able, and clear
• Phase 2 JSON format enables programmatic detection of handoff points
• Consider a global --check-manual flag that lists all manual prerequisites before running

[Kavirubc]

Hi @jpoehnelt ,

Can I work on this issue ?

Thanks.