AGENTS.md + code cleanup

AGENTS.md

@@ -0,0 +1,51 @@
+# nomyo4J — Agent Instructions
+
+Java port of the NOMYO Python client. Hybrid encryption (RSA-4096 + AES-256-GCM) for secure API communication.
+
+## Build & Run
+
+```
+mvn compile          # Java 25, Lombok annotation processor
+mvn test             # JUnit Jupiter 5.12.1, @Order enforced
+mvn test -Dtest=ClassName   # single test class
+```
+
+## Architecture
+
+- **`SecureCompletionClient`** — low-level client: key mgmt, HTTP, encryption, decryption
+- **`SecureChatCompletion`** — high-level OpenAI-compatible surface (`create()`, `acreate()`)
+- **`Constants`** — all protocol/crypto constants (version, algorithms, timeouts)
+- **`SecureMemory`** — Java 25 FFM `SecureBuffer` for locked/zeroed memory
+- **`errors/`** — exception hierarchy, all `extends Exception` (checked)
+- **`util/`** — `Pass2Key` (PBKDF2 + AES-GCM), `PEMConverter`, `Splitter`
+
+## Critical: This is a partial/in-progress port
+
+Many methods are stubbed with `UnsupportedOperationException`. Before implementing, check `TRANSLATION_REFERENCE.md` for the Python reference. Stubbed methods:
+
+- `SecureCompletionClient.fetchServerPublicKey()` — GET `/pki/public_key`
+- `SecureCompletionClient.encryptPayload()` / `doEncrypt()` — hybrid encryption
+- `SecureCompletionClient.decryptResponse()` — response decryption
+- `SecureCompletionClient.sendSecureRequest()` (3 overloads) — full request lifecycle
+- `SecureCompletionClient.ensureKeys()` — key init (partial DCL implemented)
+- `SecureCompletionClient.close()` — resource cleanup
+- `SecureChatCompletion.create()` / `acreate()` — return `null`, stubbed
+- `SecureMemory` lock/unlock — always returns `false`
+
+**No JSON library** (Jackson/Gson) in `pom.xml` — needed for wire format serialization.
+
+## Key files
+
+- `TRANSLATION_REFERENCE.md` — **primary documentation**. Cross-language spec derived from Python reference. Read before implementing any method.
+- `client_keys/` — contains real RSA keys. **Gitignored.** Do not commit.
+- `Main.java` — entry point is `static void main()` — **not `public static void main(String[])`**. Cannot run standalone.
+
+## Conventions
+
+- Package: `ai.nomyo`
+- Lombok: `@Getter` on fields, `@Setter` on static flags
+- Tests: `@TestMethodOrder(OrderAnnotation.class)`, `@DisplayName` on every test
+- Error classes: checked exceptions with `status_code` and `error_details`
+- Key files: `PosixFilePermissions.OWNER_READ` only (mode 400)
+- RSA: 4096-bit, exponent 65537, OAEP-SHA256 padding
+- Protocol constants in `Constants.java` — marked "never change"