docs: split examples into read-only basic and guarded smoke

The previous examples/basic.py ran destructive operations (configure_set,
configure_delete, generate, reset, config_file_load) by default.  That is
not what a public 'basic' example should do.

- examples/basic.py: rewritten as a read-only example
  (retrieve_show_config, show, retrieve_return_values), uses a robust
  env-bool parser, prints response.result via a small helper, and uses
  the supported public import 'from pyvyos import ApiResponse, VyDevice'.
- examples/integration_smoke.py: renamed from the old basic.py, keeps
  the mutating operations, and refuses to run unless
  PYVYOS_ALLOW_MUTATING_EXAMPLE=1 is set.
- README: link both examples and describe what each one does.

Note: the dev/ note about a future Docker-based e2e harness is tracked
in the unreleased issue drafts; it is not part of this release.

1 files changed, 8 insertions, 2 deletions

diff --git a/README.md b/README.md
index be28fa0..96c1ec8 100644
--- a/README.md
+++ b/README.md
@@ -177,8 +177,14 @@ The deprecation timeline is:
 
 ## Examples
 
-A runnable end-to-end example lives in [`examples/basic.py`](examples/basic.py),
-and a Vagrant-based lab setup under [`examples/vagrant/`](examples/vagrant/).
+- [`examples/basic.py`](examples/basic.py) — read-only end-to-end usage
+  example. Safe to run against any reachable device.
+- [`examples/integration_smoke.py`](examples/integration_smoke.py) —
+  exercises mutating operations (`configure_set/delete`, `generate`,
+  `config_file_save/load`). Intended for a disposable lab; guarded by the
+  `PYVYOS_ALLOW_MUTATING_EXAMPLE=1` environment variable.
+- [`examples/vagrant/`](examples/vagrant/) — Vagrant-based VyOS lab for
+  local development and integration testing.
 
 ## Logging