diff --git a/examples/remote-agent/README.md b/examples/remote-agent/README.md
index fb3f671..13969a0 100644
--- a/examples/remote-agent/README.md
+++ b/examples/remote-agent/README.md
@@ -27,7 +27,7 @@ curl -s -X POST http://localhost:8080/workspaces/<UUID>/secrets \
 
 # 3. Run the demo from any machine that can reach the platform:
 WORKSPACE_ID=<UUID> PLATFORM_URL=http://localhost:8080 \
-    python3 sdk/python/examples/remote-agent/run.py
+    python3 examples/remote-agent/run.py
 ```
 
 You should see log lines for each of the three phases, and then
diff --git a/molecule_agent/README.md b/molecule_agent/README.md
index 535125b..fee4bab 100644
--- a/molecule_agent/README.md
+++ b/molecule_agent/README.md
@@ -60,7 +60,7 @@ print(f"loop exited: {terminal}")
 ```
 
 A runnable demo with full setup walkthrough lives at
-[`sdk/python/examples/remote-agent/`](../examples/remote-agent).
+[`examples/remote-agent/`](https://git.moleculesai.app/Molecule-AI/molecule-sdk-python/-/tree/main/examples/remote-agent) — the runnable demo with full setup walkthrough.
 
 ## What the SDK gives you
 
@@ -282,5 +282,5 @@ the security benefits of bearer auth until both sides upgrade.
 
 - [`molecule_plugin`](../molecule_plugin) — the *other* SDK in this
   package, for plugin authors. Different audience.
-- [`sdk/python/examples/remote-agent/run.py`](../examples/remote-agent/run.py)
+- [`examples/remote-agent/run.py`](https://git.moleculesai.app/Molecule-AI/molecule-sdk-python/-/blob/main/examples/remote-agent/run.py)
   — the runnable demo that proves all of the above end-to-end.
diff --git a/molecule_agent/__init__.py b/molecule_agent/__init__.py
index a9f4f83..7a83472 100644
--- a/molecule_agent/__init__.py
+++ b/molecule_agent/__init__.py
@@ -20,7 +20,7 @@ Intended usage::
     env = client.pull_secrets()      # decrypted secrets dict
     client.run_heartbeat_loop()      # background heartbeat + state-poll
 
-See ``sdk/python/examples/remote-agent/`` for a runnable demo.
+See ``examples/remote-agent/`` for a runnable demo.
 
 Design notes:
 * **No async.** The SDK uses blocking ``requests`` so a remote agent author
diff --git a/molecule_plugin/__init__.py b/molecule_plugin/__init__.py
index 3601abc..1117f0d 100644
--- a/molecule_plugin/__init__.py
+++ b/molecule_plugin/__init__.py
@@ -26,7 +26,7 @@ Example: a minimal plugin that's installable on Claude Code and DeepAgents
         ├── claude_code.py   # `from molecule_plugin import AgentskillsAdaptor as Adaptor`
         └── deepagents.py    # same one-liner
 
-Full docs + cookiecutter template: see ``sdk/python/README.md``.
+Full docs + cookiecutter template: see the repo root ``README.md``.
 """
 
 from __future__ import annotations