docs: add AGENTS.md and gitignore AI agent local files

Add AGENTS.md as a cross-tool standard for AI coding agents with
pointers to in-tree docs, build verification commands, safety-critical
directory table, coding rules, and an agent decision framework.

Update docs/en/contribute/code.md with coding conventions enforced
during review (return early, no get/is prefixes, default member init,
no std:: in embedded code, no dynamic alloc after init).

Update docs/en/simulation/index.md with a "Choosing a Simulator"
section explaining when to use SIH vs Gazebo.

Gitignore tool-specific AI agent configs and local state for Claude
Code, Cursor, Windsurf, Aider, Cline, Continue.dev, Codex CLI,
Amazon Q, Augment, Cody, Junie, Tabnine, and Gemini.

Signed-off-by: Ramon Roche <mrpollo@gmail.com>

.gitignore

@@ -112,3 +112,38 @@ keys/
 
 # metadata
 _emscripten_sdk/
+
+# AI coding agents -- only AGENTS.md is committed
+# Tool-specific configs, settings, and local state
+.claude/
+CLAUDE.md
+CLAUDE.local.md
+.cursor/
+.cursorrules
+.cursorignore
+.cursorindexingignore
+.windsurf/
+.windsurfrules
+.codeiumignore
+.aider*
+.clinerules
+.clinerules-*
+.clineignore
+.continue/
+.continuerc.json
+.continueignore
+.codex/
+.amazonq/
+.augment/
+.augmentignore
+.augment-guidelines
+.cody/
+.junie/
+.tabnine_root
+.tabnineignore
+GEMINI.md
+.gemini/
+.geminiignore
+.aiexclude
+.mcp.json
+.claudeignore

AGENTS.md

@@ -0,0 +1,51 @@
+# AGENTS.md -- PX4-Autopilot
+
+Open-source flight controller (C/C++, NuttX/POSIX/QURT). Docs live in-tree at `docs/en/` (rendered at https://docs.px4.io).
+
+## Docs (read these first)
+
+- **Building & targets:** `docs/en/dev_setup/building_px4.md`
+- **Code style, conventions & commits:** `docs/en/contribute/code.md`
+- **Architecture & modules:** `docs/en/concept/architecture.md`
+- **uORB messaging:** `docs/en/middleware/uorb.md`
+- **Simulation (incl. choosing SIH vs Gazebo):** `docs/en/simulation/index.md`
+- **Testing:** `docs/en/test_and_ci/unit_tests.md`
+- **Test flights:** `docs/en/test_and_ci/test_flights.md`
+
+## Build Verification
+
+Always test across architectures before submitting:
+
+```bash
+make px4_sitl_default           # POSIX / SITL
+make px4_fmu-v6x_default        # STM32H7 (Pixhawk 6X)
+make px4_fmu-v5x_default        # STM32F7 (Pixhawk 5X)
+make nxp_fmuk66-v3_default      # NXP K66
+```
+
+## Areas That Benefit From Extra Review
+
+| Directory | Controls | Before modifying |
+|-----------|----------|------------------|
+| `src/modules/commander/` | Arming, failsafe, mode transitions | Verify failsafe in SITL for all vehicle types |
+| `src/modules/ekf2/` | State estimation | Run EKF replay tests |
+| `src/modules/mc_*_control/` | Multicopter controllers | Test in SIH; verify all MC airframes |
+| `src/modules/fw_*/` | Fixed-wing controllers | Test FW airframes in SITL |
+| `src/modules/vtol_att_control/` | VTOL transitions | Test MC + FW modes and transitions |
+| `msg/*.msg` | uORB schemas | Check all publishers/subscribers |
+| `ROMFS/px4fmu_common/init.d/` | Startup & default params | Can change behavior on all boards |
+
+## Rules
+
+- Never bypass safety checks (arming, geofence, failsafe) without justification
+- Document parameter changes, they affect flight behavior
+- Specify units in comments for physical quantities
+- No magic numbers, use named `constexpr` constants
+
+## Agent Decision Framework
+
+**Do without asking:** write or update the docs, ensure successful build, ensure CI checks are successful, run `make format`, add tests for new features or fixes.
+
+**Ask first:** parameter defaults, control algorithms, failsafe logic, uORB schema changes, board configs.
+
+**Stop, do not proceed:** if you can't verify flight safety, if modifying EKF2/controller math without SITL/SIH, if removing safety guards.

docs/en/contribute/code.md

@@ -86,6 +86,20 @@ private:
 };
 ```
 
+## Coding Conventions
+
+The following conventions are enforced during code review:
+
+- **Return early** to reduce nesting depth.
+- **No `get`/`is` prefixes** on boolean methods: prefer `enabled()` over `isEnabled()`.
+- **Default member initialization** in class headers, not constructors (e.g. `float _value{0.f};`).
+- **Avoid `goto`.**
+- **Prefer `++i`** over `i++`.
+- **No `std::` containers or algorithms** in embedded (NuttX) code.
+- **No dynamic memory allocation after init.**
+
+Formatting source of truth: `Tools/astyle/astylerc`. Run `make format` to fix formatting project-wide, or `Tools/astyle/fix_code_style.sh <file>` for a single file.
+
 ## In-Source Documentation
 
 PX4 developers are encouraged to create appropriate in-source documentation.

docs/en/simulation/index.md

@@ -24,6 +24,13 @@ The following simulators are supported by the PX4 core development team.
 
 There are also a number of [Community Supported Simulators](../simulation/community_supported_simulators.md).
 
+### Choosing a Simulator
+
+- **SIH (Simulation In Hardware):** Quick verification, no GPU needed, headless CI, basic flight logic testing. Runs as a PX4 module (no external process). Ideal for controller and estimator validation.
+- **Gazebo:** Sensor simulation (camera, lidar, depth), multi-vehicle, visual testing, environment interaction. Requires more resources.
+
+Use SIH when you need fast, lightweight testing of control logic or CI pipelines. Use Gazebo when you need realistic sensor data or visual environment interaction.
+
 ---
 
 The remainder of this topic is a "somewhat generic" description of how the simulation infrastructure works.