docs: Add AI contribution guidelines

Add AI coding assistant policy to CONTRIBUTING.md, modelled on the
Linux kernel's coding-assistants.rst.  Covers DCO/Signed-off-by
restrictions, licensing requirements, and the Assisted-by attribution
format.

Add AGENTS.md with codebase guidance for AI coding assistants.

Assisted-by: Claude:claude-opus-4-6
Signed-off-by: David Gibson <david@gibson.dropbear.id.au>

AGENTS.md

@@ -0,0 +1,96 @@
+# AGENTS.md
+
+This file provides guidance to AI coding assistants when working with
+code in this repository.
+
+## Build and Test
+
+The build system is Meson (the legacy Makefile still works but is
+deprecated).
+
+```sh
+# Configure and build
+meson setup build
+meson compile -C build
+
+# Run all tests
+meson test -C build
+
+# Run a specific test suite (libfdt, dtc, fdtget, fdtput, fdtdump, fdtoverlay, pylibfdt, utilfdt, dtbs_equal)
+meson test -C build dtc
+meson test -C build libfdt
+
+# Legacy make (deprecated, still functional)
+make
+make check          # all tests
+make checkm         # tests under valgrind
+```
+
+Optional build dependencies: libyaml (>= 0.2.3) for YAML output,
+valgrind for memory checking, swig + python3-dev for pylibfdt.
+
+## Architecture
+
+The repo contains three main components:
+
+### dtc (Device Tree Compiler)
+
+Compiles device tree source (.dts) to binary (.dtb) and vice versa. The pipeline is: parse source → live tree → flatten to blob (or reverse).
+
+- **Parsing**: `dtc-lexer.l` (flex) + `dtc-parser.y` (bison) produce a live tree from .dts source. `flattree.c` reads .dtb blobs. `fstree.c` reads /proc/device-tree style filesystem trees. `yamltree.c` writes YAML output.
+
+- **Live tree** (`livetree.c`, `dtc.h`): In-memory representation as `struct node` / `struct property` trees with labels, phandles, and source position tracking. The `struct data` type carries property values with type markers and cross-reference markers.
+- **Checks** (`checks.c`): ~50 semantic checks registered via `WARNING()`, `ERROR()`, and `CHECK()` macros into a `check_table[]`. Each check declares prerequisite checks, forming a DAG. Checks validate DT conventions (node naming, property types, interrupt structures, etc.). Use `-W`/`-E` flags to promote/demote.
+- **Output**: `flattree.c` writes .dtb blobs and assembler output. `treesource.c` writes .dts source.
+
+### libfdt (Flat Device Tree library)
+
+C library for reading/writing .dtb blobs in-place, dual-licensed
+GPL-2.0-or-later OR BSD-2-Clause. Used in bootloaders, kernels, and
+hypervisors where the full compiler isn't available.
+
+- `fdt_ro.c` — read-only access (property lookup, node traversal)
+- `fdt_rw.c` — read-write modification of existing blobs
+- `fdt_sw.c` — sequential-write creation of new blobs
+- `fdt_wip.c` — "write in place" operations (in-place modification)
+- `fdt_overlay.c` — device tree overlay application
+- `fdt_check.c` — blob validation (`fdt_check_full`)
+- `fdt_addresses.c` — address/size cell helpers
+- `version.lds` — exported symbol list; new public functions must be added here
+
+libfdt is designed to be embeddable: `Makefile.libfdt` can be included
+by external build systems. The `FDT_ASSUME_MASK` controls safety
+vs. performance tradeoffs (see `libfdt_internal.h`).
+
+### pylibfdt
+
+SWIG-generated Python bindings for libfdt
+(`pylibfdt/libfdt.i`). Functions not supportable by SWIG should be
+behind `#ifndef SWIG` in `libfdt.h`.
+
+## Tests
+
+Tests live in `tests/`. The test runner is `tests/run_tests.sh` which
+defines test groups: `libfdt_tests`, `dtc_tests`, `fdtget_tests`,
+`fdtput_tests`, `fdtoverlay_tests`, `pylibfdt_tests`, etc.
+
+Individual C test programs link against libfdt and use helpers from
+`tests/testutils.c`. Binary test trees are built from assembler macros
+in `tests/trees.S` via `tests/dumptrees.c` — if you modify
+`tests/test_tree1.dts`, you must also update `tests/trees.S`.
+
+## AI Contribution Policy
+
+See the "AI Coding Assistants" section in CONTRIBUTING.md. Key rules:
+
+- **Do not** add `Signed-off-by` tags — only humans can certify the DCO
+- Use `Assisted-by: AGENT_NAME:MODEL_VERSION [TOOL1] [TOOL2]` for attribution in commit messages
+- The human submitter is responsible for reviewing all AI-generated code and ensuring license compliance
+
+## Coding Conventions
+
+- License: GPL-2.0-or-later for dtc tools; (GPL-2.0-or-later OR BSD-2-Clause) for libfdt
+- SPDX identifiers on every file
+- C style follows kernel conventions: tabs for indentation, `lower_case` names
+- Compiler warnings are errors (`-Werror`)
+- libfdt functions return negative `FDT_ERR_*` codes on failure (never errno)

CONTRIBUTING.md

@@ -77,3 +77,51 @@ from people handling and transporting the patch, but were not involved
 in its development. SoB chains should reflect the **real** route a
 patch took as it was propagated to the maintainers, with the first SoB
 entry signalling primary authorship of a single author.
+
+## AI Coding Assistants
+
+AI tools helping with dtc/libfdt development must follow the standard
+contribution process described in this document.
+
+### Licensing and Legal Requirements
+
+All contributions must comply with the project's licensing requirements:
+
+* All code must be compatible with GPL-2.0-or-later
+  * All libfdt code must also be compatible with BSD-2-Clause
+* Use appropriate SPDX license identifiers
+
+### Signed-off-by and Developer Certificate of Origin
+
+AI agents MUST NOT add Signed-off-by tags. Only humans can legally
+certify the Developer Certificate of Origin (DCO). The human submitter
+is responsible for:
+
+* Reviewing all AI-generated code
+* Ensuring compliance with licensing requirements
+* Adding their own Signed-off-by tag to certify the DCO
+* Taking full responsibility for the contribution
+
+### Attribution
+
+When AI tools contribute to development, proper attribution helps track
+the evolving role of AI in the development process.  Contributions
+should include an `Assisted-by` tag in the following format:
+
+```
+Assisted-by: AGENT_NAME:MODEL_VERSION [TOOL1] [TOOL2]
+```
+
+Where:
+
+* `AGENT_NAME` is the name of the AI tool or framework
+* `MODEL_VERSION` is the specific model version used
+* `[TOOL1] [TOOL2]` are optional specialized analysis tools used
+  (e.g., coccinelle, sparse, smatch, clang-tidy)
+
+Basic development tools (git, gcc, make, editors) should not be listed.
+
+Example:
+```
+Assisted-by: Claude:claude-3-opus coccinelle sparse
+```