# AmoosedWeb SDK integration guidelines for agents

Use this guide when helping a third-party developer integrate AmoosedWeb into
a site, application, service, or game. Check the current package and platform
status before writing installation steps. The [SDK overview](api.html),
[complete Reader signatures](reader-reference.html), [site integration guide](integration.html),
and [technical reference](reference.html) describe the public interfaces.
The [illustrated protocol guide](protocol.html) introduces the data path before
the exact [wire specification](FORMAT.md).

## Select the available interface

| Need | Start here | Availability |
| --- | --- | --- |
| Build and package a carrier-backed site | [Compiler CLI](api.html#cli) and [host contract](SITE-INTEGRATION.md) | Published compiler packages |
| Read verified resources in Node.js | [Node Reader](api.html#node) | Published `amoosedweb-reader` package |
| Read verified resources in .NET | [.NET Reader](api.html#dotnet) | Published Reader package; check its supported native runtime |
| Integrate directly from C/C++ | [Native API](native-api.html), [Reader C ABI](abi.html), and [compiler C ABI](compiler-abi.html) | Reader prebuilt SDK binaries are local review previews; compiler C binary remains owner-side |
| Integrate Unreal | [Unreal guide](unreal.html) | Review preview; check the exact engine and platform claim |

Do not give a registry install command for a review-only native, Unreal, or
native-backed language package. API documentation is public even when the
corresponding implementation is not yet a public download. Each distributed
package's own license controls its use; [Pricing](https://www.amoosed.com/pricing.html)
and [Licensing](https://www.amoosed.com/licensing.html) explain the package
categories. Native implementation source is a separate licensed member
artifact, not part of the public headers and prebuilt binary SDK.
The [protocol and developer examples license](PROTOCOL-LICENSE.txt) covers
the published format specifications and example code.

## Implement and verify an integration

1. Identify the target OS, architecture, runtime or engine version, index
   mode, member access needs, and intended output. Match these to an actually
   available package and its documented platform support.
2. Use the published package's public API and runnable example. Keep index
   credentials and member keys in private files or appropriate secret storage.
   Do not put them in routine API URLs, command arguments, logs, source, or
   public site output. When a publisher intentionally distributes a key-link
   or QR invitation, treat its URL as a transferable bearer credential and
   limit distribution to the intended audience. A `.amwkey`, packed index ICO,
   or `.amwmember` is likewise a transferable bearer credential.
3. Verify the index before trusting its resource metadata. Let the Reader
   authenticate every carrier part and complete resource before parsing or
   displaying returned bytes. Treat a size query as metadata, not verification
   of resource contents.
4. Use a fresh destination for downloads. Readers do not overwrite existing
   files. A whole-site pull can leave earlier verified files if a later item
   fails; inspect the result and rerun into a new directory if a complete copy
   is required. Check final bytes or hashes in the consumer application.
5. For hosted sites, verify the exact origin, HTTPS, app/runtime routes, range
   behavior, and byte preservation with the [host contract](SITE-INTEGRATION.md).
   Test the deployed host; a local build does not prove deployment.
6. Report the installed package version, target platform, credential mode,
   fixture or site tested, exact bytes or metadata checked, and remaining
   limitations. Do not claim support for an untested carrier or platform.

## Native API and ABI rules

The public C++17 headers are a source-level API and do not promise a portable
C++ binary ABI. The current C symbols use experimental `amw_preview_*`
[revision and capabilities](abi.html); query both from the loaded library and
fail closed on a mismatch. The [proposed 1.0 ABI](ABI-1.0-DESIGN.md) describes
future `amw1_*` rules; it is not a shipped 1.0 library.

At the C boundary, pass text as strict UTF-8 bytes with an explicit length,
and binary credentials as bytes. Respect caller-owned buffers, opaque handle
release functions, and per-handle serialization. Prepare a single-use operation
before asynchronous work if another thread must cancel it; release the
operation only after the worker returns. Check numeric status categories rather
than parsing diagnostic text. Unknown nonzero statuses are failures. Keep a
download destination inside a caller-trusted directory and do not reuse an
existing target.
The [plain-C memory example](examples/native-c-memory.c) shows the current
size query, bounded caller-owned allocation, verified read, and buffer cleanup.

The [wire format](FORMAT.md) and API/ABI revisions evolve independently. A
new codec in a Reader does not by itself mean that an old binary or wrapper
supports it. Use capability and platform evidence from the package you load.

Never describe a public hosted index as confidential, a shared key as personal
identity, a hash as publisher authentication, or a key rotation as revocation
of already copied releases. See the [access model](ENTITLEMENTS.md).