chore: import upstream snapshot with attribution

docs/python/quickstart.mdx

@@ -0,0 +1,155 @@
+---
+title: Python Quickstart
+icon: /images/python-logo.svg
+description: Create a Mirage Python workspace, mount RAM as a virtual filesystem, and run shell commands that read, write, search, and transform files.
+keywords: ["Mirage Python quickstart", "mirage-ai", "virtual filesystem", "AI agents", "shell commands"]
+---
+
+## Installation
+
+Install Mirage:
+
+```bash
+uv add mirage-ai
+```
+
+If you are not using uv:
+
+```bash
+pip install mirage-ai
+```
+
+For resources with extra dependencies, install the matching extra:
+
+```bash
+uv add "mirage-ai[s3]"
+```
+
+## Create a Workspace
+
+Start with the RAM resource so you can try Mirage without credentials.
+
+```python
+import asyncio
+
+from mirage import MountMode, Workspace
+from mirage.resource.ram import RAMResource
+
+
+async def main() -> None:
+    ws = Workspace({"/data": RAMResource()}, mode=MountMode.WRITE)
+
+    await ws.execute('echo "hello mirage" | tee /data/hello.txt')
+    result = await ws.execute("cat /data/hello.txt")
+    print(await result.stdout_str())
+
+    await ws.close()
+
+
+asyncio.run(main())
+```
+
+## Run Commands
+
+Once a resource is mounted, you can use Mirage like a shell over your
+virtual filesystem:
+
+```python
+import asyncio
+
+from mirage import MountMode, Workspace
+from mirage.resource.ram import RAMResource
+
+
+async def main() -> None:
+    ws = Workspace({"/data": RAMResource()}, mode=MountMode.WRITE)
+
+    await ws.execute('echo \'{"name": "alice"}\' | tee /data/user.json')
+
+    result = await ws.execute("ls /data/")
+    print(await result.stdout_str())
+
+    result = await ws.execute("cat /data/hello.txt")
+    print(await result.stdout_str())
+
+    result = await ws.execute('jq ".name" /data/user.json')
+    print(await result.stdout_str())
+
+    result = await ws.execute("grep hello /data/hello.txt")
+    print(await result.stdout_str())
+
+    await ws.close()
+
+
+asyncio.run(main())
+```
+
+## Estimate Before You Run
+
+`execute(..., provision=True)` returns a `ProvisionResult` instead of
+running the command: network/cache bytes, read ops, and a `precision`
+telling you how much to trust the numbers (`exact`, `range`,
+`unknown` -- totals under `unknown` are floors). Pipelines, `&&`/`||`,
+`if`/`case`, loops, and subshells aggregate automatically.
+
+```python
+plan = await ws.execute("cat /data/user.json | wc -l", provision=True)
+print(plan.network_read, plan.read_ops, plan.precision)
+```
+
+Read commands are estimated out of the box on every backend. When you
+register your own command, pass `provision=` to the `@command`
+decorator (reuse a helper like `make_file_read_provision(my_stat)` or
+`default_provision(name, my_stat)` from
+`mirage.commands.builtin.generic_bind`), or omit it and the planner
+reports `unknown`. Full semantics live in the
+[CLI provision docs](/home/cli#5-dry-run-with-provision).
+
+## Output Safeguards
+
+To keep huge reads from flooding an agent, `cat`, `grep`, `rg`, `head`,
+and `tail` cap their **final** output at 2000 lines by default. When a
+cap fires, the agent sees the truncated bytes plus a stderr notice
+(`output truncated at safeguard limit (2000 lines); ...`); exit code
+stays 0.
+
+Caps fire only on the **terminal** command of a pipeline, so
+`cat big.txt | head -n 30` still shows 30 lines.
+
+### Configure per mount
+
+Limits are per-command and per-mount. Attach them when you mount a
+resource by passing a `(resource, mode, {command: CommandSafeguard})`
+tuple. Each guard sets `max_lines` / `max_bytes` (output cap) and/or
+`timeout_seconds` (deadline); `on_exceed` is `TRUNCATE` (default, exit 0
+plus notice) or `ERROR` (exit 1 plus notice):
+
+```python
+from mirage import MountMode, Workspace
+from mirage.resource.ram import RAMResource
+from mirage.types import CommandSafeguard, OnExceed
+
+ws = Workspace(
+    {
+        "/data": (
+            RAMResource(),
+            MountMode.WRITE,
+            {
+                "head": CommandSafeguard(max_lines=100),  # cap, keep going
+                "grep": CommandSafeguard(max_lines=50, on_exceed=OnExceed.ERROR),
+                "rg": CommandSafeguard(timeout_seconds=30),  # deadline
+            },
+        ),
+    },
+    mode=MountMode.WRITE,
+)
+```
+
+The same limits are available to the CLI as a `command_safeguards`
+block in the workspace YAML.
+
+## Next Steps
+
+- See [Python Installation](/python/install) for resource extras and the `uv` workflow.
+- Browse [Python Agents](/python/agents/index) to wire Mirage into the OpenAI Agents SDK, LangChain, Pydantic AI, CAMEL, and OpenHands.
+- Pick a real backend from [Resource Docs](/python/resource/index), such as [S3](/python/resource/s3), [Slack](/python/resource/slack), or [GitHub](/python/resource/github).