docs: document instanceof narrowing limitation, recommend isOk()/isErr()

README.md

@@ -146,7 +146,10 @@ and leans on several of its generics features:
 - **Sealed interface** — `Result` is annotated with `@phpstan-sealed Ok|Err`, so
   PHPStan knows `Ok` and `Err` are the only implementations. A `match (true)` over
   `instanceof` checks is recognized as exhaustive, and the `else` branch of an
-  `instanceof Ok` check narrows to `Err`.
+  `instanceof Ok` check narrows to `Err`. Note that `instanceof` narrowing loses
+  the type arguments (a known PHPStan limitation: `Result<int, E>` narrows to
+  plain `Ok`, so `unwrap()` becomes `mixed`) — use `instanceof` for exhaustiveness
+  checks only, and narrow with `isOk()`/`isErr()` when you need the values.
 - **Covariant type parameters** — `T` and `E` are declared `@template-covariant`,
   so `Ok<T>` (which is `Result<T, never>`) and `Err<E>` (which is `Result<never, E>`)
   are assignable to any `Result<T, E>`. A function declared to return

src/Result.php

@@ -7,6 +7,10 @@
 /**
  * Result型は、成功（Ok）または失敗（Err）を表現します。
  *
+ * 注意: instanceof による絞り込みでは型引数が失われます（PHPStan の既知の制限。
+ * Result<int, E> が型引数なしの Ok になり unwrap() は mixed になる）。
+ * 値を取り出す分岐では isOk() / isErr() で絞り込んでください。
+ *
  * @template-covariant T 成功時の値の型
  * @template-covariant E 失敗時のエラーの型
  *