Docs: @arg type and signature type hint relationship is ambiguous

[nihilok]

Problem

The docs show two ways to specify argument types:

1. In the @arg attribute: # @arg cmd string Command to run
2. In the function signature: on_mailserver(cmd: str)

The docs example shows both used together:

```bash

@arg env Target environment (staging|prod)

deploy(env: str, version = "latest") { ... }
```

But it's not clear whether:

• Both are required, or just one?
• Do they need to agree? What happens if they conflict?
• Is the type in @arg purely for documentation/MCP schema, while the signature hint drives actual behaviour, or vice versa?

Suggestion

Add a short note clarifying the relationship — e.g. "the type in @arg sets the MCP JSON schema type; the type hint in the signature drives runtime conversion in polyglot functions; for shell functions only the @arg type matters for MCP exposure."