graph TD
    Client[Python SDK / CLI / Agent] -->|Auth, profile, quota| API[api.jioaicloud.com]
    Client -->|Metadata, folders, trash, share| JAWS[jaws-api.jioaicloud.com]
    Client -->|Direct binary streaming| CDN[jaws-dl.jioaicloud.com]
    Client -->|Shared albums & boards| Boards[boards.jioaicloud.com]
    Client -->|Address book| Contacts[jaws-contacts.jioaicloud.com]
    Client -->|Promo banners| Msg[jaws-msg.jioaicloud.com]

jiocloud_client/
├── README.md                  # This file
├── LICENSE                    # MIT + trademark/non-affiliation notice
├── CHANGELOG.md               # Release history with verification stamps
├── CONTRIBUTING.md            # Broken-endpoint reports, capture-based fixes
├── cli.py                     # Command-line interface (20 commands)
├── config.example.json        # Credential template (placeholders only)
├── mkdocs.yml                 # Documentation site config (GitHub Pages)
├── llms.txt / llms-full.txt   # LLM-oriented documentation indexes
├── jiocloud/                  # Core SDK package
│   ├── client.py              # JioCloudClient — 30+ methods, retry engine
│   ├── auth.py                # JioCloudAuth — header construction
│   ├── agent_tools.py         # AI-agent schema, bridge, MCP stdio loop
│   ├── models.py              # Typed dataclasses
│   └── exceptions.py          # Typed error taxonomy
├── docs/                      # Also rendered at ns81000.github.io/jiocloud_client
│   ├── API_REFERENCE.md       # Every verified endpoint + payloads
│   ├── AUTHENTICATION.md      # Headers, token extraction, safety
│   ├── GET_CREDENTIALS.md     # Credential walkthrough (console one-paste)
│   ├── DATA_MODELS.md         # JSON schemas
│   ├── ERROR_CODES.md         # Server error codes seen in production
│   ├── KNOWN_ISSUES.md        # Verified server behaviors & gaps (contribute!)
│   ├── DISCLAIMER.md          # Full legal disclaimers
│   └── LEGAL.md               # Compliance summary
├── ai/                        # AI integration assets
│   ├── skills/jio-cloud-manager/SKILL.md
│   ├── tools/openai-function-schema.json
│   ├── tools/anthropic-tools.json
│   ├── prompts/system-prompt.txt
│   └── examples/agent-conversation.md
├── examples/                  # 01_quickstart ... 08_inventory_export (+ setup_credentials.py)
└── tests/
    ├── test_models.py         # Offline unit tests
    ├── test_client.py         # Live integration tests
    └── live_verify.py         # 26-check live verification matrix

python examples/setup_credentials.py --from-curl

{
  "auth_token": "Basic YOUR_BASE64_SESSION_TOKEN_HERE",
  "user_id": "YOUR_32_CHAR_USER_ID_HEX",
  "device_key": "YOUR_DEVICE_KEY_UUID",
  "api_key": "c153b48e-d8a1-48a0-a40d-293f1dc5be0e",
  "app_secret": "ODc0MDE2M2EtNGY0MC00YmU2LTgwZDUtYjNlZjIxZGRkZjlj",
  "client_details": "clientType:WEB; appVersion:86.0.1",
  "device_type": "W",
  "accept_language": "en-US,en;q=0.9"
}

from jiocloud import JioCloudClient, format_bytes

client = JioCloudClient.from_config("config.json")

profile = client.get_user_profile()
q = profile.quota
print(f"{profile.name}: {q.total_used_gb:.1f}/{q.total_allocated_gb:.0f} GB")

# Stream every file in the account
for f in client.stream_all_files():
    print(f.object_name, f.human_size)

# Search everywhere, then download matches
for hit in client.search_files("invoice", filter_extension="pdf")[:5]:
    client.download_file(hit.object_key, f"./{hit.object_name}")

python cli.py info                 # account overview + usage bar
python cli.py list --limit 20      # list root files
python cli.py tree                 # recursive tree view
python cli.py search resume --ext pdf
python cli.py download <key> -d ./out/
python cli.py sync --dest ./backup --workers 6
python cli.py mkdir Reports
python cli.py rename <key> "new name.pdf"
python cli.py move <key> <folder-key>
python cli.py favorite <key>
python cli.py share <key>          # public link
python cli.py versions <key>       # version history
python cli.py recent               # recent activity feed
python cli.py boards list|create|members
python cli.py contacts             # address book summary
python cli.py promotions           # storage promos
python cli.py trash <key> / restore <key> / trash-list

# Dump the 16-tool JSON schema into any LLM's tools parameter
python cli.py agent schema

# One-shot structured call (strict JSON envelope)
python cli.py agent call '{"tool":"search_files","arguments":{"query":"tax","extension":"pdf"}}'

# MCP-style stdio server loop for agent hosts
python cli.py agent serve

// request
{"tool": "<name>", "arguments": {...}}
// response — success
{"ok": true, "result": ...}
// response — failure (never a raw traceback)
{"ok": false, "error": {"type": "...", "message": "..."}}
// destructive tools (download_file, download_all, move_to_trash,
// restore_from_trash, share_link) REQUIRE arguments.confirm === true

python cli.py agent serve

# Offline unit tests
python -m unittest discover -s tests

# FULL live matrix against production (requires config.json).
# Exercises every read endpoint plus a complete create→rename→favorite→
# trash→restore→trash cycle and a real small-file download.
python tests/live_verify.py