Update to MarcoPolo

{
  "name": "using-connection-cli",
  "description": "Reference for the in-workspace `connection` CLI — verb shape, JSON envelope, the capability rule, and per-verb flag details. Use this skill whenever any `connection` verb (`list`, `add`, `test`, `describe`, `query`, `browse`, `download`, `upload`) is about to run, when looking up flags, when checking whether a verb is allowed by a connection's capabilities, or when reading the JSON response. Consult it even for routine commands — guessing flag names or capability-gating leads to wasted work and surprising failures.",
  "included_files": [
    {
      "relative_path": "references/add.md",
      "size_in_bytes": 1898
    },
    {
      "relative_path": "references/browse.md",
      "size_in_bytes": 1478
    },
    {
      "relative_path": "references/describe.md",
      "size_in_bytes": 1657
    },
    {
      "relative_path": "references/download.md",
      "size_in_bytes": 1560
    },
    {
      "relative_path": "references/list.md",
      "size_in_bytes": 1249
    },
    {
      "relative_path": "references/query.md",
      "size_in_bytes": 5753
    },
    {
      "relative_path": "references/test.md",
      "size_in_bytes": 865
    },
    {
      "relative_path": "references/upload.md",
      "size_in_bytes": 1119
    }
  ],
  "skill_md_contents": "---\nname: using-connection-cli\ndescription: Reference for the in-workspace `connection` CLI — verb shape, JSON envelope, the capability rule, and per-verb flag details. Use this skill whenever any `connection` verb (`list`, `add`, `test`, `describe`, `query`, `browse`, `download`, `upload`) is about to run, when looking up flags, when checking whether a verb is allowed by a connection's capabilities, or when reading the JSON response. Consult it even for routine commands — guessing flag names or capability-gating leads to wasted work and surprising failures.\n---\n\n# Using the `connection` CLI\n\nThe `connection` CLI is the verb surface for all connection work inside\nthe MarcoPolo workspace. It runs in the workspace pod; from a session,\ninvoke it through `workspace_shell`:\n\n```\nworkspace_shell(\"connection <verb> [args] --json\")\n```\n\nAlways pass `--json`. The output is then a structured envelope you can\nparse — without `--json` you get human-formatted text that's harder to\nwork with programmatically.\n\n## JSON envelope\n\nEvery `--json` response has at least:\n\n```json\n{ \"success\": true | false, \"operation\": \"<verb>\", ... }\n```\n\nOn failure: `error`, usually `message`, and often `next_actions` and\n(for unknown types) `suggested_types`. On success: verb-specific fields\ndocumented in the per-verb references below.\n\n## Capability rule\n\n`connection list --json` returns each connection's `capabilities` array.\nThat list is **authoritative** — never call `browse`, `download`, or\n`upload` on a connection unless the verb appears in its capabilities.\n\nThe reason: capabilities depend on connection type, the user's auth\nstate, and platform configuration. Calling a non-advertised verb wastes\nwork, may produce confusing errors, and clutters the workspace's audit\ntrail. The `connections/<name>/README.md` file mirrors the same\ncapabilities — both come from the same source.\n\n## Verbs at a glance\n\n| Verb | What it does | Reference |\n|---|---|---|\n| `list` | Discover connections + capabilities | `references/list.md` |\n| `add` | Get a browser setup URL for a credentialed connection | `references/add.md` |\n| `test` | Verify stored credentials | `references/test.md` |\n| `describe` | Write metadata snapshots into `connections/<name>/metadata/` | `references/describe.md` |\n| `query` | Execute a saved query file; materialize result into DuckDB | `references/query.md` |\n| `browse` (gated) | List provider-side files for storage connections | `references/browse.md` |\n| `download` (gated) | Fetch a provider file into the workspace | `references/download.md` |\n| `upload` (gated) | Push a workspace file to the provider | `references/upload.md` |\n\nRead the per-verb reference before running a verb you haven't run\nrecently, especially for flags. The references include the exact\nresponse shape, common pitfalls, and follow-on commands.\n\n**`connection query` — three facts that cause most retries:**\n- **Path:** `--file` resolves from `/workspace`, ignoring cwd. Always pass\n  `connections/<name>/queries/<file>`; a bare `queries/<file>` fails with\n  \"No such file or directory\" even if the file was just created.\n- **`--sample-rows`:** defaults to 10 — omitting it silently truncates `preview`.\n  Use a higher value to get more rows, or `-1` to get all rows in the payload.\n- **Response:** `preview` is a JSON-encoded *string* — call `json.loads` on it\n  to get records; `rows` in the envelope is an int count, not a record list.\n  The full result lives in DuckDB as `relation_name`.\n\nSee `references/query.md` for the full flag contract and response shape.\n\n## Self-discovery\n\nWhen in doubt, ask the CLI directly:\n\n```\nworkspace_shell(\"connection --help\")\nworkspace_shell(\"connection <verb> --help\")\n```\n\nThese are the live source of truth for flags. Prefer them over guessing\nor relying on the references if the workspace platform may have moved\nahead of this skill.\n\n## Pointers\n\n- adding a connection end to end → `setup-connection`\n- writing and running a query → `query-and-analyze`\n- workspace layout and where files belong → `using-marcopolo-workspace`\n"
}