docs: Document @micropython.native usage policy.

CONTRIBUTING.md

@@ -35,6 +35,7 @@ lib/<component>/
 - **Time**: use `from time import sleep_ms` (not `utime`, not `sleep()` with float seconds).
 - **Exceptions**: use `except Exception:` instead of bare `except:`. Enforced by ruff (E722).
 - **No debug `print()`** in production driver code. Enforced by ruff (T20, examples and tests excluded).
+- **`@micropython.native`**: do **not** use in driver code (`device.py`) — methods are dominated by I2C/SPI bus time, so native compilation gains nothing and reduces debuggability. In **examples**, it may be used on rendering hot-paths (tight pixel loops, math-heavy drawing functions) where a measurable speedup is expected. Do not apply it to functions with only a few comparisons or I/O calls. Note: the native emitter does not support generators, closures, or `with` statements.
 
 ## Driver API conventions
 

lib/bq27441/examples/tamagotchi.py

@@ -13,6 +13,7 @@
 import random
 from time import sleep_ms, ticks_diff, ticks_ms
 
+import micropython
 import ssd1327
 from bq27441 import BQ27441
 from machine import I2C, SPI, Pin
@@ -227,6 +228,7 @@ def wait_for_button():
     return None
 
 
+@micropython.native
 def draw_character(cx, cy, scale, sprite):
     """Draw a scaled pixel-art sprite on the display framebuf."""
     fb = display.framebuf

lib/ism330dl/examples/maze_game.py

@@ -18,6 +18,7 @@
 import random
 from time import sleep_ms
 
+import micropython
 import ssd1327
 from ism330dl import ISM330DL
 from machine import I2C, SPI, Pin
@@ -183,6 +184,7 @@ def cell_to_pixel(row, col):
     return SAFE_X + col * CELL_SIZE, SAFE_Y + row * CELL_SIZE
 
 
+@micropython.native
 def draw_maze(maze):
     """Draw all maze walls as filled rectangles."""
     for row in range(len(maze)):

lib/ism330dl/examples/spirit_level.py

@@ -9,6 +9,7 @@
 
 from time import sleep_ms
 
+import micropython
 import ssd1327
 from ism330dl import ISM330DL
 from machine import I2C, SPI, Pin
@@ -38,6 +39,7 @@
 POLL_RATE_MS = 20
 
 
+@micropython.native
 def fill_circle(fbuf, x0, y0, r, c):
     """Helper to draw a filled circle since framebuf lacks it natively."""
     for y in range(-r, r + 1):

lib/ssd1327/examples/rotating_3d_cube.py

@@ -1,5 +1,6 @@
 import math
 
+import micropython
 import ssd1327
 from machine import SPI, Pin
 
@@ -27,6 +28,7 @@
 r = [0, 0, 0]
 
 
+@micropython.native
 def draw_cube():
     r[0] = r[0] + pi / 180.0
     r[1] = r[1] + pi / 180.0

lib/vl53l1x/examples/radar_screen.py

@@ -7,7 +7,6 @@
 
 from time import sleep_ms
 
-import micropython
 import ssd1327
 from machine import I2C, SPI, Pin
 from steami_screen import DARK, GRAY, LIGHT, RED, Screen, SSD1327Display
@@ -29,7 +28,6 @@
 tof = VL53L1X(i2c)
 
 
-@micropython.native
 def compute_display(distance):
     """Compute proximity and color from distance value.