Document the public API style and drop DESIGN_REVIEW references

Add a Public API style section to AGENTS.md summarising the workspace
specs/api-style.md rules, and point at it from the spec table.

DESIGN_REVIEW.md was removed from the workspace; open questions now live
inline in the specs. Reword the code and test comments that cited it.

Author: lijy91

AGENTS.md

@@ -26,14 +26,15 @@ submodule. Read them before adding or reshaping public API:
 | --- | --- |
 | `../specs/architecture.md` | Layering, the six-platform matrix, naming, build |
 | `../specs/object-model.md` | Identity objects vs value objects |
+| `../specs/api-style.md` | Method vocabulary, parameter/return types, failure reporting, doc comments |
 | `../specs/platform-seam.md` | PIMPL, narrow seams, `NativeObjectProvider` |
 | `../specs/event-system.md` | `Event` / `EventEmitter`, threading, lazy listening |
 | `../specs/managers.md` | Singletons, registries, the handle table |
 | `../specs/c-abi.md` | What codegen produces and how types cross the boundary |
 | `../specs/handle-ownership.md` | C ABI handle ownership and invalidation |
 
-`../DESIGN_REVIEW.md` tracks the *unresolved* inconsistencies; the specs describe what is
-already settled.
+Each spec also records the open questions and known legacy gaps of its own area inline;
+there is no separate issue list.
 
 ## Non-negotiables
 
@@ -52,6 +53,37 @@ already settled.
    [src/foundation/id_allocator.h](src/foundation/id_allocator.h) — append only, never
    renumber.
 
+## Public API style
+
+The full rules and the review checklist are in `../specs/api-style.md`. Everything public in
+`src/*.h` is exported verbatim to C, Dart, Rust and C#, so the short version is:
+
+- **Properties** are `SetX(v)` + `GetX() const`, booleans `SetX(bool is_x)` + `IsX() const`,
+  declared as an adjacent pair. Getters are always `const` — codegen only turns `const`
+  no-arg `Get`/`Is`/`Has` methods into binding properties.
+- **Actions** are bare imperative verbs with a fixed opposite (`Show`/`Hide`, `Open`/`Close`,
+  `Maximize`/`Unmaximize`, `Enable`/`Disable`) and an `IsXxx() const` state query.
+- **No new overloads** — they surface as `native_x_verb_with_<params>`. Different meaning,
+  different name (`RemoveItemById`, `RemoveItemAt`).
+- **Types**: strings in as `const std::string&`, out by value; geometry and enums by value;
+  identity objects only as `std::shared_ptr<T>` (`nullptr` = none), never `const T&` / `T*`;
+  `std::optional` wraps strings only; floating point is `double`; IDs use the `XxxId` alias.
+- **Enums**: `enum class`, PascalCase values, no `k` prefix, sequential from 0, first value
+  is the neutral default, append only.
+- **Failure**: never throw across the public API. `void` when it cannot fail, `bool` when a
+  platform may not support it (document what `false` means), `nullptr` for lookups and
+  factories. Do not invent another error channel.
+- **Platform differences live in the doc comment**, not the signature: every API exists on
+  all six platforms, and one that behaves differently carries the six-line
+  `@note Platform availability:` block (✅ / ⚠️ / ❌).
+- **"Intercept before X" is a cancellable event on the object**, not another
+  `SetWillXxxHook`; internal entry points stay out of the `public:` section.
+- After editing a header, run `./codegen` from the workspace root and make sure no
+  `skipped` warning names the new API.
+
+Where existing headers disagree, the spec says which side is the rule — do not copy the
+nearest neighbour.
+
 ## Naming
 
 - C++ — classes and methods `PascalCase`, members `snake_case_`, files `snake_case.h`,

src/foundation/handle_table.h

@@ -51,8 +51,8 @@ class HandleTable {
    * @brief Process-wide table.
    *
    * A singleton for now, matching how the C ABI is structured. It is a Meyer's
-   * singleton like the rest of the library; the explicit-lifetime work in
-   * DESIGN_REVIEW §4.2 will fold this into the same Context as the others.
+   * singleton like the rest of the library; if the singletons are ever folded
+   * into an explicit-lifetime Context, this one goes with them.
    */
   static HandleTable& GetInstance();
 

src/foundation/id_allocator.h

@@ -14,8 +14,8 @@ namespace nativeapi {
  * T is a compile error rather than a silent runtime surprise.
  *
  * These values are stable identifiers, not arbitrary numbers. They appear in
- * the high bits of every ID handed out, and the handle-table work described in
- * DESIGN_REVIEW §P0-4 will use them to reject type-confused handles crossing
+ * the high bits of every ID handed out, and the handle table
+ * (foundation/handle_table.h) uses them to reject type-confused handles crossing
  * the C ABI. Therefore:
  *
  *   - NEVER renumber an existing entry.

tests/event_emitter_test.cpp

@@ -1,6 +1,6 @@
 // Regression tests for EventEmitter locking and dispatch behaviour.
 //
-// Every case here maps to a defect described in DESIGN_REVIEW.md:
+// Every case here maps to a defect that was found and fixed:
 //   P0-1  EmitAsync self-deadlock (recursive lock on queue_mutex_)
 //   P0-2  Emit invoking listener callbacks while holding listeners_mutex_
 //

tests/handle_table_test.cpp

@@ -1,6 +1,6 @@
 // Tests for the generational handle table.
 //
-// Maps to DESIGN_REVIEW.md P0-3 / P0-4 and docs/handle-ownership.md. The
+// The rules are in the workspace repo, specs/handle-ownership.md. The
 // behaviours asserted here are exactly the ones raw-pointer handles could not
 // provide: stale handles failing safely instead of dereferencing freed memory,
 // double-release being a no-op, and handle confusion being rejected rather than

tests/id_allocator_test.cpp

@@ -1,6 +1,6 @@
 // Tests for IdAllocator's ID encoding and type tagging.
 //
-// Maps to DESIGN_REVIEW.md P1-5: type tags used to be handed out by a runtime
+// Regression background: type tags used to be handed out by a runtime
 // counter on a first-call-wins basis, so a given C++ type could receive a
 // different tag depending on call order or from one run to the next. That made
 // the type bits useless for the handle validation they are meant to support.