Update README.md

AGENTS.md

@@ -0,0 +1,55 @@
+# Domito contributor guidance
+
+Applies to this repository and its subdirectories.
+
+## Purpose and boundaries
+
+- Domito is a kernel-mode SDK for Windows Code Integrity and mincrypt APIs. Preserve usable C exports and types, source compatibility and native ABI accuracy.
+- Implementation sources may use modest C++ conveniences. Public headers and examples must remain consumable from kernel-mode C without WDF/DMF dependencies.
+- Reuse CI and Windows cryptographic primitives. Keep signature verification separate from application authorization, publisher allowlists, root pins, request caching, developer bypasses and expiry policy.
+- Never copy private consumer implementations, identifiers, paths, revisions, publisher strings or pins into source, tests, documentation or commit messages. Use independently written generic code and synthetic/public fixtures.
+- Keep changes focused. Additional kernel experiments and broader research belong in follow-up work unless requested.
+
+## Code style and notation
+
+- Follow the existing library style in `src/Domito.cpp`, `src/Domito.Memory.cpp` and surrounding declarations. Apply it to new helpers, tests and C documentation examples as well.
+- Use four spaces, Allman braces and braces for every control-flow body. Expand conditionals and cleanup; do not put multiple statements or returns on one line.
+- Put return types on their own line, followed by the function name. Use multiline parameter lists with one parameter per line and the closing parenthesis on its own line. Keep SAL annotations, linkage and return types on separate lines.
+- Declare variables separately, use descriptive local names and separate logical operations with blank lines. Avoid compressed declaration lists, opaque abbreviations and unnecessary `auto` where the concrete type clarifies ownership.
+- Use `Domito` function names, `DOMITO_*` public type/constant names, PascalCase parameters and lowerCamelCase locals. Preserve native `MINCRYPT_*` declarations and existing public names rather than introducing cosmetic ABI/API churn.
+- Match nearby pointer, cast and initialization conventions. C examples must use C-compatible syntax. Preserve UTF-8, CRLF and existing BOMs when editing files.
+- Write comments about contracts, ownership and non-obvious reasoning. Distinguish recovered analyst names from official Windows terminology; avoid repetitive implementation narration.
+- Prefer readable, normally formatted Python runners. Do not compress setup, subprocess invocation or assertions into one-liners.
+
+## API and ownership contracts
+
+- Declare accurate SAL/IRQL requirements in public headers. Use `_Use_decl_annotations_` for corresponding definitions when appropriate. Validation, file I/O and certificate helpers run at PASSIVE_LEVEL; synchronous I/O also needs special kernel APCs enabled.
+- Return useful NTSTATUS values. Initialize outputs before fallible work, publish owning outputs only when valid, and handle partially populated outputs on failure.
+- Zero-initialize owning CI results before first use. Release both signer and timestamp policies, including diagnostic allocations on failure, and clean old results before reuse. Never copy an owning result into a second owner.
+- Borrowed certificate, SPKI and chain views expire with their backing buffer or policy. Do not free child blobs separately. CI hash outputs are file digests, not certificate thumbprints.
+- Pair each allocation with its documented destructor. Configurable Domito allocator pairs must remain compatible and unchanged while calls or callback-backed allocations are outstanding; replacement is not synchronized.
+- Keep caller-owned handles open and balance object references. KernelMode handle references require trusted handles; never feed unchecked user handles into them. Path/name lookup does not prove original process-image or in-memory identity.
+- Module/export lookup does not pin a module. Require valid loader-mapped input and caller-provided module lifetime; reject unsupported forwarders.
+- Preserve legacy entry points where compatibility requires them. Mark superseded functions/types with `__declspec(deprecated("migration guidance"))` when an actual safer replacement exists. Name the replacement and semantic changes. Do not deprecate raw native ABI types just because a convenience view exists.
+- Suppress C4996 only locally for intentional compatibility code/tests, never globally. Keep deprecation compiler checks effective for consumers.
+
+## CI, PE and certificate correctness
+
+- Consult `docs/mincrypt-contracts.md`, `docs/ci-api-compatibility.md`, `docs/ci-validate-file-object.md`, `docs/authenticode-digests.md` and the helper contracts before changing native assumptions.
+- Export presence and compile-time NTDDI guards do not establish runtime ABI compatibility. Chain allocation `Size` is not a layout version. Historical and architecture-specific views need explicit evidence; unknown layouts must not be guessed.
+- `0x20` broadens accepted roots in examined CI builds; it is not a generic PE-image marker. `0x80`/first-success selection remains experimental, has other policy effects and does not select an arbitrary publisher/signature index.
+- Preserve explicit algorithm, flag, signing-level, catalog and selection choices. Do not silently add root-acceptance flags, retry weaker algorithms, fall back to catalogs or change signer-selection policy.
+- Check API status separately from policy verification status and application trust requirements. A nonzero signing time alone does not establish the intended signer or trust policy.
+- Bound PE/DER parsing and arithmetic before reading or allocating. Preserve the documented supported PE subset instead of claiming a universal Authenticode/SIP parser. Exact reads must complete before cleanup and must reject short reads.
+- Make certificate hash representation explicit: entire certificate DER, complete SPKI DER TLV, or legacy SPKI content excluding its outer tag/length. They produce different pins. Reject malformed hex; do not map invalid characters to zero.
+- Bounded chain access is not independent cryptographic chain validation. Do not promise that the last represented certificate is a trusted/self-signed root or impose bytewise issuer/subject equality as a universal CI invariant.
+
+## Validation and evidence
+
+- Follow `tests/README.md` for the six host runners. Preserve extraction of actual production code; formatting changes must not silently replace it with a copied implementation in tests.
+- Use meaningful negative, truncation, capacity, ownership and failure-path checks. For deprecation changes verify C4996 and modern controls in C/C++ on x64/ARM64.
+- Compile affected library sources and public C clients with the WDK for x64/ARM64; retain `/kernel /W4 /WX` and check relevant layouts. Run static analysis when contracts or cleanup change.
+- Host doubles, Windows cryptographic comparisons and compilation do not establish real kernel CI policy, runtime ABI, failure ownership or enforcement behavior. Report those limits explicitly.
+- Use the separate research repository/probe for runtime evidence. Record exact OS/CI/fixture identities, enforcement settings, both policy statuses, selected certificate, signing time and trace health. Do not generalize one TESTSIGNING-enabled run to other builds or TESTSIGNING-off systems.
+- Keep binaries, PDBs, private keys, raw machine traces and temporary build outputs out of source commits. Do not load a driver or change trust stores, boot policy or enforcement on a development host as part of ordinary build/test work.
+- Keep `docs/implementation-status.md` current when evidence changes a support claim. Summarize completed checks and remaining runtime work without presenting pending experiments as verified behavior.

README.md

@@ -54,10 +54,13 @@ Application authorization and trust policies remain caller-provided.
 - Add includes (preferably in the provided order):
   ```c
   #include <ntddk.h>
+  #include <ntintsafe.h>
   #include <ntimage.h>
   #include <bcrypt.h>
   #include <Domito.h>
   ```
+  `Domito.h` also includes the consumer helper declarations; no separate
+  `Domito.Consumer.h` include is required.
 - Call `DomitoInit()` in your `DriverEntry` once to bootstrap internals.
 
 ### Manual linker settings
@@ -96,7 +99,6 @@ For example:
 - [Algorithm-explicit Authenticode hashing and legacy catalog policy](docs/authenticode-digests.md)
 - [Mincrypt contracts, lifetimes, flags and opt-in x64 26100 layouts](docs/mincrypt-contracts.md)
 - [Implemented corrections and remaining VM/binary work](docs/implementation-status.md)
-
 - [CiValidateFileObject flag 0x20: evidence, limitations, and kernel test procedure](docs/ci-validate-file-object.md)
 
 ## Sources & 3rd party credits