chore: import upstream snapshot with attribution

examples/python/google/docs.py

@@ -0,0 +1,101 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import asyncio
+import json
+import os
+
+from dotenv import load_dotenv
+
+from mirage import MountMode, Workspace
+from mirage.resource.gdocs import GDocsConfig, GDocsResource
+
+load_dotenv(".env.development")
+
+config = GDocsConfig(
+    client_id=os.environ["GOOGLE_CLIENT_ID"],
+    client_secret=os.environ["GOOGLE_CLIENT_SECRET"],
+    refresh_token=os.environ["GOOGLE_REFRESH_TOKEN"],
+)
+resource = GDocsResource(config=config)
+
+
+async def main():
+    ws = Workspace({"/gdocs": resource}, mode=MountMode.WRITE)
+
+    r = await ws.execute("ls /gdocs/owned/ | head -n 3")
+    print("=== ls (first 3) ===")
+    print(await r.stdout_str())
+
+    first = (await r.stdout_str()).strip().split("\n")[0]
+
+    print("=== plan: cat ===")
+    dr = await ws.execute(f"cat /gdocs/owned/{first}", provision=True)
+    print(f"  network_read={dr.network_read}, precision={dr.precision}")
+
+    print("=== plan: grep ===")
+    dr = await ws.execute(f"grep textRun /gdocs/owned/{first}", provision=True)
+    print(f"  network_read={dr.network_read}, precision={dr.precision}")
+
+    print("=== jq .title ===")
+    r = await ws.execute(f'jq ".title" /gdocs/owned/{first}')
+    print(await r.stdout_str())
+
+    print("=== head -c 200 ===")
+    r = await ws.execute(f"head -c 200 /gdocs/owned/{first}")
+    print(await r.stdout_str())
+
+    print("=== grep textRun ===")
+    r = await ws.execute(f"grep textRun /gdocs/owned/{first} | head -c 200")
+    print(await r.stdout_str())
+
+    print("=== tail -c 200 ===")
+    r = await ws.execute(f"tail -c 200 /gdocs/owned/{first}")
+    print(await r.stdout_str())
+
+    print("=== gws-docs-documents-create ===")
+    r = await ws.execute('gws-docs-documents-create'
+                         ' --json \'{"title": "MIRAGE Example Doc"}\'')
+    doc = json.loads(await r.stdout_str())
+    doc_id = doc["documentId"]
+    print(f"Created: {doc_id}")
+
+    print("\n=== gws-docs-documents-batchUpdate ===")
+    body = json.dumps({
+        "requests": [{
+            "insertText": {
+                "location": {
+                    "index": 1
+                },
+                "text": "Hello from MIRAGE!\n",
+            }
+        }]
+    })
+    params = json.dumps({"documentId": doc_id})
+    r = await ws.execute(f"gws-docs-documents-batchUpdate"
+                         f" --params '{params}' --json '{body}'")
+    print(f"Updated: {(await r.stdout_str())[:80]}")
+
+    print("\n=== gws-docs-write ===")
+    r = await ws.execute(f'gws-docs-write'
+                         f' --document {doc_id}'
+                         f' --text "Appended via gws-docs-write."')
+    print(f"Written: {(await r.stdout_str())[:80]}")
+
+    url = f"https://docs.google.com/document/d/{doc_id}/edit"
+    print(f"\nOpen: {url}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/python/google/docs_vfs.py

@@ -0,0 +1,78 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import asyncio
+import json
+import os
+import sys
+
+from dotenv import load_dotenv
+
+from mirage import MountMode, Workspace
+from mirage.resource.gdocs import GDocsConfig, GDocsResource
+
+load_dotenv(".env.development")
+
+config = GDocsConfig(
+    client_id=os.environ["GOOGLE_CLIENT_ID"],
+    client_secret=os.environ["GOOGLE_CLIENT_SECRET"],
+    refresh_token=os.environ["GOOGLE_REFRESH_TOKEN"],
+)
+resource = GDocsResource(config=config)
+
+
+async def main():
+    with Workspace({"/gdocs/": resource}, mode=MountMode.READ) as ws:
+        vos = sys.modules["os"]
+        print(
+            "=== VFS MODE: open() reads from Google Docs transparently ===\n")
+
+        print("--- os.listdir() root ---")
+        dirs = vos.listdir("/gdocs")
+        for d in dirs:
+            print(f"  {d}")
+
+        print("\n--- os.listdir() owned ---")
+        docs = vos.listdir("/gdocs/owned")
+        for doc in docs[:5]:
+            print(f"  {doc}")
+
+        if docs:
+            first = docs[0]
+            path = f"/gdocs/owned/{first}"
+            print("\n--- open() + read first doc ---")
+            with open(path) as f:
+                content = f.read()
+                parsed = json.loads(content)
+                print(f"  title: {parsed.get('title', 'N/A')}")
+                print(f"  content preview: {content[:200]}...")
+
+            print("\n--- os.path.exists() ---")
+            print(f"  {first}: {vos.path.exists(path)}")
+            print(
+                f"  nonexistent: {vos.path.exists('/gdocs/owned/nope.json')}")
+
+        print("\n--- bash history ---")
+        with open("/.bash_history") as f:
+            for i, line in enumerate(f):
+                if i >= 6:
+                    break
+                print(f"  {line.rstrip()[:120]}")
+
+        records = ws.ops.records
+        total = sum(r.bytes for r in records)
+        print(f"\nStats: {len(records)} ops, {total} bytes transferred")
+
+
+asyncio.run(main())

examples/python/google/gdrive.py

@@ -0,0 +1,77 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import asyncio
+import os
+
+from dotenv import load_dotenv
+
+from mirage import MountMode, Workspace
+from mirage.resource.gdrive import GoogleDriveConfig, GoogleDriveResource
+
+load_dotenv(".env.development")
+
+config = GoogleDriveConfig(
+    client_id=os.environ["GOOGLE_CLIENT_ID"],
+    client_secret=os.environ["GOOGLE_CLIENT_SECRET"],
+    refresh_token=os.environ["GOOGLE_REFRESH_TOKEN"],
+)
+resource = GoogleDriveResource(config=config)
+
+
+async def main():
+    ws = Workspace({"/gdrive": resource}, mode=MountMode.READ)
+
+    print("=== ls /gdrive/ (first 10) ===")
+    r = await ws.execute("ls /gdrive/ | head -n 10")
+    print(await r.stdout_str())
+
+    r = await ws.execute("ls /gdrive/ | head -n 30")
+    listing = await r.stdout_str()
+    gdoc = gsheet = gslide = None
+    for line in listing.strip().split("\n"):
+        f = line.strip()
+        if ".gdoc.json" in f and not gdoc:
+            gdoc = f
+        if ".gsheet.json" in f and not gsheet:
+            gsheet = f
+        if ".gslide.json" in f and not gslide:
+            gslide = f
+
+    if gdoc:
+        print(f"=== jq .title on {gdoc} ===")
+        r = await ws.execute(f'jq ".title" "/gdrive/{gdoc}"')
+        print(await r.stdout_str())
+
+        print(f"=== head -c 150 on {gdoc} ===")
+        r = await ws.execute(f'head -c 150 "/gdrive/{gdoc}"')
+        print(await r.stdout_str())
+
+    if gslide:
+        print(f"\n=== jq .title on {gslide} ===")
+        r = await ws.execute(f'jq ".title" "/gdrive/{gslide}"')
+        print(await r.stdout_str())
+
+        print("=== jq slides length ===")
+        r = await ws.execute(f'jq ".slides | length" "/gdrive/{gslide}"')
+        print(await r.stdout_str())
+
+    if gsheet:
+        print(f"\n=== jq .properties.title on {gsheet} ===")
+        r = await ws.execute(f'jq ".properties.title" "/gdrive/{gsheet}"')
+        print(await r.stdout_str())
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/python/google/gdrive_complex.py

@@ -0,0 +1,487 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import asyncio
+import json
+import os
+
+from dotenv import load_dotenv
+
+from mirage import MountMode, Workspace
+from mirage.resource.gdrive import GoogleDriveConfig, GoogleDriveResource
+
+load_dotenv(".env.development")
+
+config = GoogleDriveConfig(
+    client_id=os.environ["GOOGLE_CLIENT_ID"],
+    client_secret=os.environ["GOOGLE_CLIENT_SECRET"],
+    refresh_token=os.environ["GOOGLE_REFRESH_TOKEN"],
+)
+
+backend = GoogleDriveResource(config=config)
+ws = Workspace({"/gdrive/": backend}, mode=MountMode.READ)
+
+
+def ops_summary() -> str:
+    records = ws.ops.records
+    total = sum(r.bytes for r in records)
+    return f"{len(records)} ops, {total} bytes transferred"
+
+
+async def main():
+    # ── prime the cache: gdrive resolves paths via file IDs ──
+    await ws.execute("ls /gdrive/")
+    await ws.execute("ls /gdrive/mirage/")
+
+    # ── plan: estimate before executing ──
+    print("=== PLAN ESTIMATES ===\n")
+
+    dr = await ws.execute("grep mirage /gdrive/mirage/example.jsonl",
+                          provision=True)
+    print("--- plan: grep mirage /gdrive/mirage/example.jsonl ---")
+    print(f"  network_read: {dr.network_read}, cache_read: {dr.cache_read}")
+    print(f"  read_ops: {dr.read_ops}, precision: {dr.precision}")
+
+    dr = await ws.execute(
+        "grep mirage /gdrive/mirage/example.jsonl | head -n 3", provision=True)
+    print("\n--- plan: grep mirage ... | head -n 3 ---")
+    print(f"  op: {dr.op}, children: {len(dr.children)}")
+    print(f"  network_read: {dr.network_read}, cache_read: {dr.cache_read}")
+    print(f"  precision: {dr.precision}")
+    for c in dr.children:
+        net, cache = c.network_read, c.cache_read
+        print(f"    {c.command}: net={net}, cache={cache}, {c.precision}")
+
+    dr = await ws.execute(
+        "grep mirage /gdrive/mirage/example.jsonl && echo found",
+        provision=True)
+    print("\n--- plan: grep ... && echo found ---")
+    print(f"  op: {dr.op}, network_read: {dr.network_read}")
+    for c in dr.children:
+        print(f"    {c.command}: net={c.network_read}, {c.precision}")
+
+    print(f"\n  Stats after plans (should be 0): {ops_summary()}")
+
+    # ── cache-aware plan ──
+    print("\n--- caching: cat /gdrive/mirage/example.jsonl | wc -l ---")
+    result = await ws.execute("cat /gdrive/mirage/example.jsonl | wc -l")
+    print(f"  lines: {(await result.stdout_str()).strip()}")
+    print(f"  Stats after caching: {ops_summary()}")
+
+    dr = await ws.execute("grep mirage /gdrive/mirage/example.jsonl",
+                          provision=True)
+    print("\n--- plan after cache: grep mirage ... ---")
+    print(f"  network_read: {dr.network_read}, cache_read: {dr.cache_read}")
+    print(f"  cache_hits: {dr.cache_hits}, read_ops: {dr.read_ops}")
+
+    print("\n=== ACTUAL EXECUTION ===\n")
+
+    # ── simple grep ──
+    print("--- grep mirage /gdrive/mirage/example.jsonl ---")
+    output = await (
+        await
+        ws.execute("grep mirage /gdrive/mirage/example.jsonl")).stdout_str()
+    lines = output.strip().splitlines() if output.strip() else []
+    print(f"  Matches: {len(lines)}")
+    if lines:
+        print(f"  First: {lines[0][:80]}...")
+    print(f"  Stats: {ops_summary()}")
+
+    # ── grep with limit ──
+    print("\n--- grep -m 1 mirage /gdrive/mirage/example.jsonl ---")
+    output = await (await
+                    ws.execute("grep -m 1 mirage /gdrive/mirage/example.jsonl")
+                    ).stdout_str()
+    lines = output.strip().splitlines() if output.strip() else []
+    print(f"  Matches: {len(lines)}")
+    print(f"  Stats: {ops_summary()}")
+
+    # ── pipe: grep | wc -l ──
+    print("\n--- grep mirage /gdrive/mirage/example.jsonl | wc -l ---")
+    result = await ws.execute(
+        "grep mirage /gdrive/mirage/example.jsonl | wc -l")
+    print(f"  Count: {(await result.stdout_str()).strip()}")
+    print(f"  Exit code: {result.exit_code}")
+    print(f"  Stats: {ops_summary()}")
+
+    # ── pipe: grep | head ──
+    print("\n--- grep mirage /gdrive/mirage/example.jsonl | head -n 3 ---")
+    result = await ws.execute(
+        "grep mirage /gdrive/mirage/example.jsonl | head -n 3")
+    lines = (await result.stdout_str()).strip().splitlines()
+    print(f"  Lines: {len(lines)}")
+    for ln in lines:
+        print(f"    {ln[:80]}...")
+    print(f"  Stats: {ops_summary()}")
+
+    # ── pipe: cat | grep | sort | uniq ──
+    print("\n--- cat /gdrive/mirage/example.jsonl"
+          " | grep queue-operation | sort | uniq ---")
+    result = await ws.execute("cat /gdrive/mirage/example.jsonl"
+                              " | grep queue-operation | sort | uniq")
+    lines = ((await result.stdout_str()).strip().splitlines() if
+             (await result.stdout_str()).strip() else [])
+    print(f"  Unique lines: {len(lines)}")
+    print(f"  Stats: {ops_summary()}")
+
+    # ── pipe: grep | cut (extract field) ──
+    print("\n--- rg queue-operation /gdrive/mirage/example.jsonl"
+          " | head -n 5 | cut -d , -f 2 ---")
+    result = await ws.execute("rg queue-operation /gdrive/mirage/example.jsonl"
+                              " | head -n 5 | cut -d , -f 2")
+    print(f"  Fields:\n    {(await result.stdout_str()).strip()}")
+    print(f"  Stats: {ops_summary()}")
+
+    # ── && chain: grep && echo ──
+    print("\n--- grep -m 1 mirage /gdrive/mirage/example.jsonl"
+          " && echo 'found mirage' ---")
+    result = await ws.execute(
+        "grep -m 1 mirage /gdrive/mirage/example.jsonl && echo found")
+    print(f"  Exit code: {result.exit_code}")
+    print(
+        f"  Stdout ends with: ...{(await result.stdout_str()).strip()[-30:]}")
+    print(f"  Stats: {ops_summary()}")
+
+    # ── || chain: grep nonexistent || echo fallback ──
+    print("\n--- grep NONEXISTENT /gdrive/mirage/example.jsonl"
+          " || echo 'not found' ---")
+    result = await ws.execute(
+        "grep NONEXISTENT /gdrive/mirage/example.jsonl || echo not_found")
+    print(f"  Exit code: {result.exit_code}")
+    print(f"  Output: {(await result.stdout_str()).strip()}")
+    print(f"  Stats: {ops_summary()}")
+
+    # ── subshell: (grep | sort | uniq) | wc -l ──
+    print("\n--- (grep queue-operation /gdrive/mirage/example.jsonl"
+          " | sort | uniq) | wc -l ---")
+    result = await ws.execute(
+        "(grep queue-operation /gdrive/mirage/example.jsonl"
+        " | sort | uniq) | wc -l")
+    print(f"  Unique queue ops: {(await result.stdout_str()).strip()}")
+    print(f"  Stats: {ops_summary()}")
+
+    # ── semicolon: multiple independent reads ──
+    print("\n--- head -n 1 /gdrive/mirage/example.jsonl"
+          " ; wc -l /gdrive/mirage/example.jsonl ---")
+    result = await ws.execute("head -n 1 /gdrive/mirage/example.jsonl"
+                              " ; wc -l /gdrive/mirage/example.jsonl")
+    print(f"  Output: {(await result.stdout_str()).strip()}")
+    print(f"  Stats: {ops_summary()}")
+
+    # ── lazy multi-pipe: grep | grep | head | cut ──
+    print("\n--- lazy multi-pipe: grep | grep -v | head | cut ---")
+    result = await ws.execute(
+        "grep queue-operation /gdrive/mirage/example.jsonl"
+        " | grep -v error | head -n 2 | cut -d , -f 1")
+    print(f"  Output:\n    {(await result.stdout_str()).strip()}")
+
+    result_full = await ws.execute(
+        "grep queue-operation /gdrive/mirage/example.jsonl"
+        " | grep -v error | cut -d , -f 1")
+    full_lines = (await result_full.stdout_str()).strip().splitlines()
+    print(f"  Without head: {len(full_lines)} lines (full download)")
+
+    # ── recursive search ──
+    print("\n--- rg -l mirage /gdrive/mirage ---")
+    output = await (await
+                    ws.execute("rg -l mirage /gdrive/mirage")).stdout_str()
+    lines = output.strip().splitlines() if output.strip() else []
+    print(f"  Files: {lines}")
+    print(f"  Stats: {ops_summary()}")
+
+    # ── Google native files: docs, sheets, slides ──
+    print("\n=== GOOGLE NATIVE FILES ===\n")
+
+    print("--- ls /gdrive (find native files) ---")
+    r = await ws.execute("ls /gdrive/ | head -n 20")
+    print(f"  {(await r.stdout_str()).strip()}")
+
+    print("\n--- grep in Google Docs (.gdoc.json) ---")
+    r = await ws.execute("ls /gdrive/")
+    listing = (await r.stdout_str()).strip().splitlines()
+    gdoc = next((f.strip() for f in listing if ".gdoc.json" in f), None)
+    if gdoc:
+        print(f"  Found doc: {gdoc}")
+        r = await ws.execute(f'grep -i "title" "/gdrive/{gdoc}"')
+        out = (await r.stdout_str()).strip()
+        if out:
+            print(f"  grep title: {out[:120]}...")
+        print(f"  Stats: {ops_summary()}")
+    else:
+        print("  No .gdoc.json found in /gdrive/")
+
+    gsheet = next((f.strip() for f in listing if ".gsheet.json" in f), None)
+    if gsheet:
+        print("\n--- grep in Google Sheets (.gsheet.json) ---")
+        print(f"  Found sheet: {gsheet}")
+        r = await ws.execute(
+            f'grep -i "properties" "/gdrive/{gsheet}" | head -n 3')
+        out = (await r.stdout_str()).strip()
+        if out:
+            print(f"  grep properties: {out[:120]}...")
+        print(f"  Stats: {ops_summary()}")
+
+    gslide = next((f.strip() for f in listing if ".gslide.json" in f), None)
+    if gslide:
+        print("\n--- grep in Google Slides (.gslide.json) ---")
+        print(f"  Found slide: {gslide}")
+        r = await ws.execute(f'grep -i "slide" "/gdrive/{gslide}" | head -n 3')
+        out = (await r.stdout_str()).strip()
+        if out:
+            print(f"  grep slide: {out[:120]}...")
+        print(f"  Stats: {ops_summary()}")
+
+    # ── mixed file type grep ──
+    print("\n=== MIXED FILE TYPE GREP ===\n")
+
+    print("--- grep -c title in Google Doc (eager read) ---")
+    if gdoc:
+        r = await ws.execute(f'grep -c title "/gdrive/{gdoc}"')
+        print(f"  {gdoc}: {(await r.stdout_str()).strip()} matches")
+
+    print("\n--- grep in regular file (streaming) ---")
+    r = await ws.execute("grep -c queue-operation /gdrive/mirage/example.jsonl"
+                         )
+    print(f"  example.jsonl: {(await r.stdout_str()).strip()} matches")
+
+    print("\n--- rg across mirage folder (regular files) ---")
+    r = await ws.execute("rg -l queue /gdrive/mirage/")
+    files = (await r.stdout_str()).strip().splitlines()
+    print(f"  Files matching 'queue': {files}")
+    print(f"  Stats: {ops_summary()}")
+
+    # ── filetype: parquet, orc, feather, hdf5 ──
+    print("\n=== FILETYPE: parquet, orc, feather, hdf5 ===\n")
+
+    for label, path in [
+        ("parquet", "/gdrive/mirage/example.parquet"),
+        ("orc", "/gdrive/mirage/example.orc"),
+        ("feather", "/gdrive/mirage/example.feather"),
+        ("hdf5", "/gdrive/mirage/example.h5"),
+    ]:
+        print(f"--- grep item_5 {label} ---")
+        r = await ws.execute(f"grep item_5 {path}")
+        print(f"  exit={r.exit_code}  {(await r.stdout_str()).strip()[:100]}")
+
+    print("\n--- cat parquet | head -n 3 ---")
+    r = await ws.execute("cat /gdrive/mirage/example.parquet | head -n 3")
+    print(f"  {(await r.stdout_str()).strip()}")
+
+    print("\n--- wc -l across formats ---")
+    for label, path in [
+        ("parquet", "/gdrive/mirage/example.parquet"),
+        ("orc", "/gdrive/mirage/example.orc"),
+        ("feather", "/gdrive/mirage/example.feather"),
+        ("hdf5", "/gdrive/mirage/example.h5"),
+    ]:
+        r = await ws.execute(f"wc -l {path}")
+        print(f"  {label}: {(await r.stdout_str()).strip()}")
+
+    print(f"  Stats: {ops_summary()}")
+
+    # ── jq: structured JSON queries ──
+    print("\n=== JQ QUERIES ===\n")
+
+    print("--- jq .metadata ---")
+    result = await ws.execute("jq .metadata /gdrive/mirage/example.json")
+    print(f"  {(await result.stdout_str()).strip()}")
+
+    print("\n--- jq: all team names (nested [] iterator) ---")
+    result = await ws.execute(
+        "jq \".departments[].teams[].name\" /gdrive/mirage/example.json")
+    print(f"  {(await result.stdout_str()).strip()}")
+
+    print("\n--- jq: all employee names ---")
+    result = await ws.execute("jq \".departments[].teams[].members[].name\""
+                              " /gdrive/mirage/example.json")
+    print(f"  {(await result.stdout_str()).strip()}")
+
+    print("\n--- jq: senior engineers on platform ---")
+    result = await ws.execute("jq \".departments[0].teams[0].members"
+                              " | map(select(.level == \\\"senior\\\"))"
+                              " | map(.name)\" /gdrive/mirage/example.json")
+    print(f"  {(await result.stdout_str()).strip()}")
+
+    print("\n--- jq: all active project names ---")
+    result = await ws.execute("jq \".departments[].teams[].projects"
+                              " | map(select(.status == \\\"active\\\"))"
+                              " | map(.name)\" /gdrive/mirage/example.json")
+    print(f"  {(await result.stdout_str()).strip()}")
+
+    print("\n--- jq: mirage project metrics ---")
+    result = await ws.execute("jq .departments[0].teams[0].projects[0].metrics"
+                              " /gdrive/mirage/example.json")
+    print(f"  {(await result.stdout_str()).strip()}")
+
+    print("\n--- jq: total budget ---")
+    result = await ws.execute(
+        "jq .metadata.total_budget /gdrive/mirage/example.json")
+    budget = (await result.stdout_str()).strip()
+    if budget:
+        print(f"  Total budget: ${int(budget):,}")
+    else:
+        print("  (no output)")
+
+    print("\n--- jq: vendor costs ---")
+    result = await ws.execute("jq \".vendor_contracts | map(.annual_cost)\""
+                              " /gdrive/mirage/example.json")
+    print(f"  {(await result.stdout_str()).strip()}")
+
+    print("\n--- jq: office locations ---")
+    result = await ws.execute(
+        "jq \".locations | map(.city)\" /gdrive/mirage/example.json")
+    print(f"  {(await result.stdout_str()).strip()}")
+
+    print("\n--- jq: all incident titles ---")
+    result = await ws.execute("jq \".departments[].teams[].incidents[].title\""
+                              " /gdrive/mirage/example.json")
+    print(f"  {(await result.stdout_str()).strip()}")
+
+    print("\n--- jq: OKR key results ---")
+    result = await ws.execute(
+        "jq \".okrs[0].objectives[0].key_results"
+        " | map(.description)\" /gdrive/mirage/example.json")
+    print(f"  {(await result.stdout_str()).strip()}")
+
+    print("\n--- pipe: cat | jq (from cache) ---")
+    result = await ws.execute(
+        "cat /gdrive/mirage/example.json | jq .metadata.version")
+    print(f"  Version: {(await result.stdout_str()).strip()}")
+
+    # ── session: cd + export ──
+    print("\n=== SESSION: cd + export ===\n")
+
+    print("--- cd /gdrive/mirage && ls ---")
+    await ws.execute("cd /gdrive/mirage")
+    result = await ws.execute("ls")
+    print(f"  {(await result.stdout_str()).strip()}")
+
+    print("\n--- export + variable expansion ---")
+    await ws.execute("export SEARCH=mirage")
+    result = await ws.execute("grep $SEARCH example.jsonl | head -n 2")
+    print(f"  {(await result.stdout_str()).strip()[:80]}...")
+
+    print("\n--- printenv ---")
+    result = await ws.execute("printenv")
+    print(f"  {(await result.stdout_str()).strip()}")
+
+    print("\n--- plan: cd + grep ---")
+    await ws.execute("cd /gdrive/mirage")
+    dr = await ws.execute("grep mirage example.jsonl", provision=True)
+    print(f"  network_read: {dr.network_read}, cache_read: {dr.cache_read}")
+
+    # ── execution history: hidden recorder + GNU views ──
+    print("\n=== EXECUTION HISTORY ===\n")
+    events = await ws.history()
+    print(f"  Total commands recorded: {len(events)}")
+
+    entry = events[-1]
+    print(f"\n  Last command: {entry['command']}")
+    print(f"  Agent: {entry['agent']}")
+    print(f"  Exit code: {entry['exit_code']}")
+
+    print("\n  --- history (shell builtin, this session) ---")
+    r = await ws.execute("history 5")
+    for line in (await r.stdout_str()).splitlines():
+        print(f"  {line[:100]}")
+
+    print("\n  --- tail -n 6 /.bash_history (all sessions, GNU file) ---")
+    r = await ws.execute("tail -n 6 /.bash_history")
+    for line in (await r.stdout_str()).splitlines():
+        print(f"  {line[:100]}")
+
+    print("\n  --- history as JSONL ---")
+    for e in events[-3:]:
+        print(json.dumps(e, separators=(",", ":")))
+
+    # ── background jobs: & operator ──
+    print("\n=== BACKGROUND JOBS ===\n")
+
+    print("--- launch two background greps ---")
+    r = await ws.execute(
+        "grep mirage /gdrive/mirage/example.jsonl &"
+        " grep queue-operation /gdrive/mirage/example.jsonl &",
+        agent_id="demo-agent",
+    )
+    print(f"  Output: {(await r.stdout_str()).strip()}")
+
+    print("\n--- ps: show running jobs ---")
+    r = await ws.execute("ps u")
+    print(f"  {(await r.stdout_str()).strip()}")
+
+    print("\n--- jobs: list all ---")
+    r = await ws.execute("jobs")
+    print(f"  {(await r.stdout_str()).strip()}")
+
+    print("\n--- wait %1: get first grep result ---")
+    r = await ws.execute("wait %1")
+    lines = (await r.stdout_str()).strip().splitlines() if (
+        await r.stdout_str()).strip() else []
+    print(f"  Matches: {len(lines)}, exit_code: {r.exit_code}")
+    if lines:
+        print(f"  First: {lines[0][:80]}...")
+
+    print("\n--- wait %2: get second grep result ---")
+    r = await ws.execute("wait %2")
+    lines = (await r.stdout_str()).strip().splitlines() if (
+        await r.stdout_str()).strip() else []
+    print(f"  Matches: {len(lines)}, exit_code: {r.exit_code}")
+
+    print("\n--- background pipe: grep | head & ---")
+    await ws.execute(
+        "grep queue-operation /gdrive/mirage/example.jsonl | head -n 3 &")
+    r = await ws.execute("wait %3")
+    print(f"  Output:\n    {(await r.stdout_str()).strip()}")
+
+    print("\n--- kill demo ---")
+    await ws.execute("grep mirage /gdrive/mirage/example.jsonl &")
+    await ws.execute("kill %4")
+    r = await ws.execute("wait %4")
+    print(f"  Exit code after kill: {r.exit_code}")
+
+    print("\n--- wait || fallback pattern ---")
+    await ws.execute("grep NONEXISTENT /gdrive/mirage/example.jsonl &")
+    await ws.execute("grep mirage /gdrive/mirage/example.jsonl &")
+    r = await ws.execute("wait %5 || wait %6")
+    lines = (await r.stdout_str()).strip().splitlines() if (
+        await r.stdout_str()).strip() else []
+    print(f"  Fallback matches: {len(lines)}")
+
+    print("\n--- jobs after all done ---")
+    r = await ws.execute("jobs")
+    print(f"  {(await r.stdout_str()).strip() or '(empty)'}")
+
+    print("\n--- background job history ---")
+    bg_entries = [
+        e for e in await ws.history()
+        if "grep" in e["command"] and "&" not in e["command"]
+    ]
+    print(f"  Background job records: {len(bg_entries)}")
+    for e in bg_entries[-4:]:
+        print(f"    {e['command'][:60]}  exit={e['exit_code']}")
+
+    # ── bash history view ──
+    print("\n=== BASH HISTORY ===\n")
+
+    print("--- ls -a / (dotfile view) ---")
+    result = await ws.execute("ls -a /")
+    print(f"  {(await result.stdout_str()).strip()}")
+
+    print("\n--- grep grep /.bash_history | head -n 3 ---")
+    result = await ws.execute("grep grep /.bash_history | head -n 3")
+    for line in (await result.stdout_str()).strip().splitlines():
+        print(f"  {line[:120]}")
+
+
+asyncio.run(main())

examples/python/google/gdrive_vfs.py

@@ -0,0 +1,101 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import asyncio
+import json
+import os
+import sys
+
+from dotenv import load_dotenv
+
+from mirage import MountMode, Workspace
+from mirage.resource.gdrive import GoogleDriveConfig, GoogleDriveResource
+
+load_dotenv(".env.development")
+
+config = GoogleDriveConfig(
+    client_id=os.environ["GOOGLE_CLIENT_ID"],
+    client_secret=os.environ["GOOGLE_CLIENT_SECRET"],
+    refresh_token=os.environ["GOOGLE_REFRESH_TOKEN"],
+)
+resource = GoogleDriveResource(config=config)
+
+
+async def main():
+    with Workspace({"/gdrive/": resource}, mode=MountMode.READ) as ws:
+        vos = sys.modules["os"]
+        print(
+            "=== VFS MODE: open() reads from Google Drive transparently ===\n")
+
+        print("--- os.listdir() root ---")
+        entries = vos.listdir("/gdrive")
+        for e in entries[:10]:
+            print(f"  {e}")
+
+        gdoc = gsheet = gslide = None
+        for e in entries:
+            if ".gdoc.json" in e and not gdoc:
+                gdoc = e
+            if ".gsheet.json" in e and not gsheet:
+                gsheet = e
+            if ".gslide.json" in e and not gslide:
+                gslide = e
+
+        if gdoc:
+            path = f"/gdrive/{gdoc}"
+            print(f"\n--- open() Google Doc: {gdoc} ---")
+            with open(path) as f:
+                content = f.read()
+                parsed = json.loads(content)
+                print(f"  title: {parsed.get('title', 'N/A')}")
+                print(f"  preview: {content[:200]}...")
+
+        if gsheet:
+            path = f"/gdrive/{gsheet}"
+            print(f"\n--- open() Google Sheet: {gsheet} ---")
+            with open(path) as f:
+                content = f.read()
+                parsed = json.loads(content)
+                title = parsed.get("properties", {}).get("title", "N/A")
+                num_sheets = len(parsed.get("sheets", []))
+                print(f"  title: {title}")
+                print(f"  sheets: {num_sheets}")
+
+        if gslide:
+            path = f"/gdrive/{gslide}"
+            print(f"\n--- open() Google Slides: {gslide} ---")
+            with open(path) as f:
+                content = f.read()
+                parsed = json.loads(content)
+                print(f"  title: {parsed.get('title', 'N/A')}")
+                print(f"  slides: {len(parsed.get('slides', []))}")
+
+        print("\n--- os.path.exists() ---")
+        if gdoc:
+            print(f"  {gdoc}: {vos.path.exists(f'/gdrive/{gdoc}')}")
+        print(f"  nonexistent: {vos.path.exists('/gdrive/nope.txt')}")
+
+        print("\n--- bash history ---")
+        with open("/.bash_history") as f:
+            for i, line in enumerate(f):
+                if i >= 6:
+                    break
+                print(f"  {line.rstrip()[:120]}")
+
+        records = ws.ops.records
+        total = sum(r.bytes for r in records)
+        print(f"\nStats: {len(records)} ops, {total} bytes transferred")
+
+
+asyncio.run(main())

examples/python/google/gmail.py

@@ -0,0 +1,71 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import asyncio
+import os
+
+from dotenv import load_dotenv
+
+from mirage import MountMode, Workspace
+from mirage.resource.gmail import GmailConfig, GmailResource
+
+load_dotenv(".env.development")
+
+config = GmailConfig(
+    client_id=os.environ["GOOGLE_CLIENT_ID"],
+    client_secret=os.environ["GOOGLE_CLIENT_SECRET"],
+    refresh_token=os.environ["GOOGLE_REFRESH_TOKEN"],
+)
+resource = GmailResource(config=config)
+
+
+async def main():
+    ws = Workspace({"/gmail": resource}, mode=MountMode.WRITE)
+
+    r = await ws.execute("ls /gmail/")
+    print("=== labels ===")
+    print(await r.stdout_str())
+
+    r = await ws.execute("ls /gmail/INBOX/ | head -n 3")
+    print("=== INBOX (first 3) ===")
+    print(await r.stdout_str())
+
+    first = (await r.stdout_str()).strip().split("\n")[0]
+
+    print("=== plan: cat ===")
+    dr = await ws.execute(f"cat /gmail/INBOX/{first}", provision=True)
+    print(f"  network_read={dr.network_read}, precision={dr.precision}")
+
+    print("=== cat message ===")
+    r = await ws.execute(f"cat /gmail/INBOX/{first}")
+    print((await r.stdout_str())[:500])
+
+    print("=== jq .subject ===")
+    r = await ws.execute(f'jq ".subject" /gmail/INBOX/{first}')
+    print(await r.stdout_str())
+
+    print("=== gws-gmail-triage ===")
+    r = await ws.execute('gws-gmail-triage --query "is:unread" --max 5')
+    print((await r.stdout_str())[:500])
+
+    print("=== gws-gmail-send ===")
+    r = await ws.execute(
+        'gws-gmail-send --to "zechengzhang97@gmail.com"'
+        ' --subject "Hello from MIRAGE"'
+        ' --body "This email was sent via the MIRAGE Gmail resource."')
+    print((await r.stdout_str())[:200])
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/python/google/gmail_dates.py

@@ -0,0 +1,88 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import asyncio
+import os
+
+from dotenv import load_dotenv
+
+from mirage import MountMode, Workspace
+from mirage.resource.gmail import GmailConfig, GmailResource
+
+load_dotenv(".env.development")
+
+config = GmailConfig(
+    client_id=os.environ["GOOGLE_CLIENT_ID"],
+    client_secret=os.environ["GOOGLE_CLIENT_SECRET"],
+    refresh_token=os.environ["GOOGLE_REFRESH_TOKEN"],
+)
+resource = GmailResource(config=config)
+
+
+async def show(ws, cmd):
+    print(f"\n$ {cmd}")
+    r = await ws.execute(cmd)
+    out = await r.stdout_str()
+    err = await r.stderr_str()
+    if out:
+        print(f"STDOUT:\n{out}")
+    if err:
+        print(f"STDERR:\n{err}")
+    print(f"exit={r.exit_code}")
+    return out, err, r.exit_code
+
+
+async def main():
+    ws = Workspace({"/gmail": resource}, mode=MountMode.READ)
+
+    out, _, _ = await show(ws, "ls /gmail/INBOX/ | head -5")
+    dates = [d for d in out.strip().split("\n") if d]
+    if not dates:
+        print("(no dates in INBOX)")
+        return
+    first_date = dates[0]
+
+    # A date dir lists message files (*.gmail.json); a message that has
+    # attachments also gets a sibling folder named after the message.
+    out, _, _ = await show(ws, f"ls /gmail/INBOX/{first_date}")
+    entries = [e for e in out.strip().split("\n") if e]
+    msg_file = next((e for e in entries if e.endswith(".gmail.json")), None)
+    assert msg_file, f"date dir should contain a *.gmail.json msg: {entries}"
+
+    await show(
+        ws, f'cat "/gmail/INBOX/{first_date}/{msg_file}" '
+        "| jq '{subject, from: .from.email, "
+        "attachments: [.attachments[].filename]}'")
+
+    # Find a message with attachments: a date-dir entry without the
+    # .gmail.json suffix is the attachment folder for the matching message,
+    # so "<name>.gmail.json" is its message file.
+    print("\n=== finding a message with attachments ===")
+    for d in dates:
+        r = await ws.execute(f"ls /gmail/INBOX/{d}")
+        items = [e for e in (await r.stdout_str()).strip().split("\n") if e]
+        att_dir = next((e for e in items if not e.endswith(".gmail.json")),
+                       None)
+        if att_dir:
+            print(f"FOUND: /gmail/INBOX/{d}/{att_dir}")
+            await show(ws, f'ls "/gmail/INBOX/{d}/{att_dir}"')
+            await show(
+                ws, f'cat "/gmail/INBOX/{d}/{att_dir}.gmail.json" '
+                "| jq '.attachments'")
+            return
+    print("(no attachments found in scanned dates)")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/python/google/gmail_vfs.py

@@ -0,0 +1,85 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import asyncio
+import json
+import os
+import sys
+
+from dotenv import load_dotenv
+
+from mirage import MountMode, Workspace
+from mirage.resource.gmail import GmailConfig, GmailResource
+
+load_dotenv(".env.development")
+
+config = GmailConfig(
+    client_id=os.environ["GOOGLE_CLIENT_ID"],
+    client_secret=os.environ["GOOGLE_CLIENT_SECRET"],
+    refresh_token=os.environ["GOOGLE_REFRESH_TOKEN"],
+)
+resource = GmailResource(config=config)
+
+
+async def main():
+    with Workspace({"/gmail/": resource}, mode=MountMode.READ) as ws:
+        vos = sys.modules["os"]
+        print("=== VFS MODE: open() reads from Gmail transparently ===\n")
+
+        print("--- os.listdir() labels ---")
+        labels = vos.listdir("/gmail")
+        for label in labels:
+            print(f"  {label}")
+
+        print("\n--- os.listdir() INBOX (date folders) ---")
+        dates = vos.listdir("/gmail/INBOX")
+        for date in dates[:5]:
+            print(f"  {date}")
+
+        first_date = dates[0] if dates else None
+        entries = vos.listdir(
+            f"/gmail/INBOX/{first_date}") if first_date else []
+        messages = [e for e in entries if e.endswith(".gmail.json")]
+        for msg in messages[:5]:
+            print(f"  {first_date}/{msg}")
+
+        if messages:
+            first = messages[0]
+            path = f"/gmail/INBOX/{first_date}/{first}"
+            print("\n--- open() + read first message ---")
+            with open(path) as f:
+                content = f.read()
+                parsed = json.loads(content)
+                print(f"  subject: {parsed.get('subject', 'N/A')}")
+                print(f"  from: {parsed.get('from', 'N/A')}")
+                print(f"  snippet: {parsed.get('snippet', '')[:120]}...")
+
+            print("\n--- os.path.exists() ---")
+            print(f"  {first}: {vos.path.exists(path)}")
+            print(
+                f"  nonexistent: {vos.path.exists('/gmail/INBOX/nope.json')}")
+
+        print("\n--- bash history ---")
+        with open("/.bash_history") as f:
+            for i, line in enumerate(f):
+                if i >= 6:
+                    break
+                print(f"  {line.rstrip()[:120]}")
+
+        records = ws.ops.records
+        total = sum(r.bytes for r in records)
+        print(f"\nStats: {len(records)} ops, {total} bytes transferred")
+
+
+asyncio.run(main())

examples/python/google/sheets.py

@@ -0,0 +1,124 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import asyncio
+import json
+import os
+
+from dotenv import load_dotenv
+
+from mirage import MountMode, Workspace
+from mirage.resource.gsheets import GSheetsConfig, GSheetsResource
+
+load_dotenv(".env.development")
+
+config = GSheetsConfig(
+    client_id=os.environ["GOOGLE_CLIENT_ID"],
+    client_secret=os.environ["GOOGLE_CLIENT_SECRET"],
+    refresh_token=os.environ["GOOGLE_REFRESH_TOKEN"],
+)
+resource = GSheetsResource(config=config)
+
+
+async def main():
+    ws = Workspace({"/gsheets": resource}, mode=MountMode.WRITE)
+
+    r = await ws.execute("ls /gsheets/owned/ | head -n 3")
+    print("=== ls (first 3) ===")
+    print(await r.stdout_str())
+
+    first = (await r.stdout_str()).strip().split("\n")[0]
+
+    print("=== plan: cat ===")
+    dr = await ws.execute(f"cat /gsheets/owned/{first}", provision=True)
+    print(f"  network_read={dr.network_read}, precision={dr.precision}")
+
+    print("=== plan: grep ===")
+    dr = await ws.execute(f"grep title /gsheets/owned/{first}", provision=True)
+    print(f"  network_read={dr.network_read}, precision={dr.precision}")
+
+    print("=== jq .properties.title ===")
+    r = await ws.execute(f'jq ".properties.title" /gsheets/owned/{first}')
+    print(await r.stdout_str())
+
+    print('=== jq ".sheets | length" ===')
+    r = await ws.execute(f'jq ".sheets | length" /gsheets/owned/{first}')
+    print(await r.stdout_str())
+
+    print("=== head -c 200 ===")
+    r = await ws.execute(f"head -c 200 /gsheets/owned/{first}")
+    print(await r.stdout_str())
+
+    print("=== grep title ===")
+    r = await ws.execute(f"grep title /gsheets/owned/{first} | head -c 200")
+    print(await r.stdout_str())
+
+    print("=== tail -c 200 ===")
+    r = await ws.execute(f"tail -c 200 /gsheets/owned/{first}")
+    print(await r.stdout_str())
+
+    print("=== gws-sheets-spreadsheets-create ===")
+    body = json.dumps({"properties": {"title": "MIRAGE Sheets Test"}})
+    r = await ws.execute("gws-sheets-spreadsheets-create"
+                         f" --json '{body}'")
+    out = await r.stdout_str()
+    if r.exit_code != 0 or not out.strip():
+        err = (await r.stderr_str()).strip() or "empty response"
+        print(f"  create failed (exit={r.exit_code}): {err}")
+        return
+    sheet = json.loads(out)
+    sheet_id = sheet["spreadsheetId"]
+    print(f"Created: {sheet_id}")
+
+    print("\n=== gws-sheets-write ===")
+    params = json.dumps({
+        "spreadsheetId": sheet_id,
+        "range": "Sheet1!A1",
+        "valueInputOption": "USER_ENTERED",
+    })
+    values = json.dumps({
+        "values": [
+            ["Name", "Age", "City"],
+            ["Alice", "30", "NYC"],
+            ["Bob", "25", "SF"],
+        ]
+    })
+    r = await ws.execute(f"gws-sheets-write"
+                         f" --params '{params}' --json '{values}'")
+    print(f"Written: {(await r.stdout_str())[:80]}")
+
+    print("\n=== gws-sheets-read ===")
+    r = await ws.execute(f'gws-sheets-read'
+                         f' --spreadsheet {sheet_id}'
+                         f' --range "Sheet1!A1:C3"')
+    print(f"Values: {await r.stdout_str()}")
+
+    print("=== gws-sheets-append ===")
+    r = await ws.execute(f"gws-sheets-append"
+                         f" --spreadsheet {sheet_id}"
+                         f" --values Diana,28,Chicago")
+    print(f"Appended: {(await r.stdout_str())[:80]}")
+
+    print("\n=== gws-sheets-read (all) ===")
+    r = await ws.execute(f'gws-sheets-read'
+                         f' --spreadsheet {sheet_id}'
+                         f' --range Sheet1')
+    print(f"All: {await r.stdout_str()}")
+
+    url = f"https://docs.google.com/spreadsheets/d/{sheet_id}"
+    print(f"\nOpen: {url}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/python/google/sheets_vfs.py

@@ -0,0 +1,83 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import asyncio
+import json
+import os
+import sys
+
+from dotenv import load_dotenv
+
+from mirage import MountMode, Workspace
+from mirage.resource.gsheets import GSheetsConfig, GSheetsResource
+
+load_dotenv(".env.development")
+
+config = GSheetsConfig(
+    client_id=os.environ["GOOGLE_CLIENT_ID"],
+    client_secret=os.environ["GOOGLE_CLIENT_SECRET"],
+    refresh_token=os.environ["GOOGLE_REFRESH_TOKEN"],
+)
+resource = GSheetsResource(config=config)
+
+
+async def main():
+    with Workspace({"/gsheets/": resource}, mode=MountMode.READ) as ws:
+        vos = sys.modules["os"]
+        print(
+            "=== VFS MODE: open() reads from Google Sheets transparently ===\n"
+        )
+
+        print("--- os.listdir() root ---")
+        dirs = vos.listdir("/gsheets")
+        for d in dirs:
+            print(f"  {d}")
+
+        print("\n--- os.listdir() owned ---")
+        sheets = vos.listdir("/gsheets/owned")
+        for s in sheets[:5]:
+            print(f"  {s}")
+
+        if sheets:
+            first = sheets[0]
+            path = f"/gsheets/owned/{first}"
+            print("\n--- open() + read first spreadsheet ---")
+            with open(path) as f:
+                content = f.read()
+                parsed = json.loads(content)
+                title = parsed.get("properties", {}).get("title", "N/A")
+                num_sheets = len(parsed.get("sheets", []))
+                print(f"  title: {title}")
+                print(f"  sheets: {num_sheets}")
+                print(f"  preview: {content[:200]}...")
+
+            print("\n--- os.path.exists() ---")
+            print(f"  {first}: {vos.path.exists(path)}")
+            print(
+                f"  nonexistent: {vos.path.exists('/gsheets/owned/nope.json')}"
+            )
+
+        print("\n--- bash history ---")
+        with open("/.bash_history") as f:
+            for i, line in enumerate(f):
+                if i >= 6:
+                    break
+                print(f"  {line.rstrip()[:120]}")
+
+        records = ws.ops.records
+        total = sum(r.bytes for r in records)
+        print(f"\nStats: {len(records)} ops, {total} bytes transferred")
+
+
+asyncio.run(main())

examples/python/google/slides.py

@@ -0,0 +1,103 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import asyncio
+import json
+import os
+
+from dotenv import load_dotenv
+
+from mirage import MountMode, Workspace
+from mirage.resource.gslides import GSlidesConfig, GSlidesResource
+
+load_dotenv(".env.development")
+
+config = GSlidesConfig(
+    client_id=os.environ["GOOGLE_CLIENT_ID"],
+    client_secret=os.environ["GOOGLE_CLIENT_SECRET"],
+    refresh_token=os.environ["GOOGLE_REFRESH_TOKEN"],
+)
+resource = GSlidesResource(config=config)
+
+
+async def main():
+    ws = Workspace({"/gslides": resource}, mode=MountMode.WRITE)
+
+    r = await ws.execute("ls /gslides/owned/ | head -n 3")
+    print("=== ls (first 3) ===")
+    print(await r.stdout_str())
+
+    first = (await r.stdout_str()).strip().split("\n")[0]
+
+    print("=== plan: cat ===")
+    dr = await ws.execute(f"cat /gslides/owned/{first}", provision=True)
+    print(f"  network_read={dr.network_read}, precision={dr.precision}")
+
+    print("=== plan: grep ===")
+    dr = await ws.execute(f"grep textRun /gslides/owned/{first}",
+                          provision=True)
+    print(f"  network_read={dr.network_read}, precision={dr.precision}")
+
+    print("=== jq .title ===")
+    r = await ws.execute(f'jq ".title" /gslides/owned/{first}')
+    print(await r.stdout_str())
+
+    print('=== jq ".slides | length" ===')
+    r = await ws.execute(f'jq ".slides | length" /gslides/owned/{first}')
+    print(await r.stdout_str())
+
+    print("=== head -c 200 ===")
+    r = await ws.execute(f"head -c 200 /gslides/owned/{first}")
+    print(await r.stdout_str())
+
+    print("=== grep textRun ===")
+    r = await ws.execute(f"grep textRun /gslides/owned/{first} | head -c 200")
+    print(await r.stdout_str())
+
+    print("=== tail -c 200 ===")
+    r = await ws.execute(f"tail -c 200 /gslides/owned/{first}")
+    print(await r.stdout_str())
+
+    print("=== gws-slides-presentations-create ===")
+    r = await ws.execute('gws-slides-presentations-create'
+                         ' --json \'{"title": "MIRAGE Slides Test"}\'')
+    pres = json.loads(await r.stdout_str())
+    pres_id = pres["presentationId"]
+    print(f"Created: {pres_id}")
+
+    print("\n=== gws-slides-presentations-batchUpdate ===")
+    body = json.dumps({
+        "requests": [{
+            "createSlide": {
+                "insertionIndex": 1,
+                "slideLayoutReference": {
+                    "predefinedLayout": "BLANK"
+                },
+            }
+        }]
+    })
+    params = json.dumps({"presentationId": pres_id})
+    r = await ws.execute("gws-slides-presentations-batchUpdate"
+                         f" --params '{params}' --json '{body}'")
+    update = json.loads(await r.stdout_str())
+    slide_id = update["replies"][0]["createSlide"]["objectId"]
+    print(f"Added slide: {slide_id}")
+
+    url = (f"https://docs.google.com/presentation/"
+           f"d/{pres_id}/edit")
+    print(f"\nOpen: {url}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/python/google/slides_vfs.py

@@ -0,0 +1,83 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import asyncio
+import json
+import os
+import sys
+
+from dotenv import load_dotenv
+
+from mirage import MountMode, Workspace
+from mirage.resource.gslides import GSlidesConfig, GSlidesResource
+
+load_dotenv(".env.development")
+
+config = GSlidesConfig(
+    client_id=os.environ["GOOGLE_CLIENT_ID"],
+    client_secret=os.environ["GOOGLE_CLIENT_SECRET"],
+    refresh_token=os.environ["GOOGLE_REFRESH_TOKEN"],
+)
+resource = GSlidesResource(config=config)
+
+
+async def main():
+    with Workspace({"/gslides/": resource}, mode=MountMode.READ) as ws:
+        vos = sys.modules["os"]
+        print(
+            "=== VFS MODE: open() reads from Google Slides transparently ===\n"
+        )
+
+        print("--- os.listdir() root ---")
+        dirs = vos.listdir("/gslides")
+        for d in dirs:
+            print(f"  {d}")
+
+        print("\n--- os.listdir() owned ---")
+        presentations = vos.listdir("/gslides/owned")
+        for p in presentations[:5]:
+            print(f"  {p}")
+
+        if presentations:
+            first = presentations[0]
+            path = f"/gslides/owned/{first}"
+            print("\n--- open() + read first presentation ---")
+            with open(path) as f:
+                content = f.read()
+                parsed = json.loads(content)
+                title = parsed.get("title", "N/A")
+                num_slides = len(parsed.get("slides", []))
+                print(f"  title: {title}")
+                print(f"  slides: {num_slides}")
+                print(f"  preview: {content[:200]}...")
+
+            print("\n--- os.path.exists() ---")
+            print(f"  {first}: {vos.path.exists(path)}")
+            print(
+                f"  nonexistent: {vos.path.exists('/gslides/owned/nope.json')}"
+            )
+
+        print("\n--- bash history ---")
+        with open("/.bash_history") as f:
+            for i, line in enumerate(f):
+                if i >= 6:
+                    break
+                print(f"  {line.rstrip()[:120]}")
+
+        records = ws.ops.records
+        total = sum(r.bytes for r in records)
+        print(f"\nStats: {len(records)} ops, {total} bytes transferred")
+
+
+asyncio.run(main())