docs: ship agent guides and skills from every published package

CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.16.0-rc.4 (TBA)
+
+### Enhancements
+
+* [FEATURE][web][react] Every published package now ships agent-facing documentation inside its tarball: an `AGENTS.md` index plus a `skills/` directory, readable at `node_modules/@miden-sdk/<pkg>/`. Because they ship with the code they are version-matched to the installed release, so an AI agent working in a consumer's repo gets guidance for the version in that repo's lockfile rather than whatever its training data remembers. `@miden-sdk/miden-sdk` also ships its `README.md` for the first time — it previously published neither a readme nor any documentation. Paste the marker block from any package readme into your project's root `AGENTS.md` to point your agent at them. ([#310](https://github.com/0xMiden/web-sdk/pull/310))
+* [CHANGE] The skills describing this SDK's own API (`web-client-usage`, `react-sdk-patterns`, `vite-wasm-setup`, `frontend-pitfalls`, `signer-integration`, `testing-patterns`, `frontend-source-guide`) are now canonical in this repo, joined by a new `chain-anchored-execution` skill covering the `ChainAnchor` API added in 0.16.0-rc.3, having previously been maintained in [`0xMiden/agent-tools`](https://github.com/0xMiden/agent-tools) and copied into [`0xMiden/frontend-template`](https://github.com/0xMiden/frontend-template). Both copies had drifted from each other and from the code, since nothing tied a skill to the API it documented; keeping them beside the source makes an API change and its documentation the same PR. `agent-tools` remains canonical for everything not specific to this SDK. ([#310](https://github.com/0xMiden/web-sdk/pull/310))
+
 ## 0.16.0-rc.3 (2026-08-23)
 
 ### Changes

CONTRIBUTING.md

@@ -2,7 +2,7 @@
 
 We welcome PRs. Before opening one:
 
-1. Read [CLAUDE.md](CLAUDE.md) for repo-specific conventions and tooling notes.
+1. Read [AGENTS.md](AGENTS.md) for repo-specific conventions and tooling notes.
 2. Run `make lint test` locally — CI runs the same suite, but local feedback is faster.
 3. For changes that touch the public API surface (hooks, WASM bindings, plugin options), include or update the type tests in `crates/web-client/scripts/check-*-types.js`.
 

crates/web-client/AGENTS.md

@@ -0,0 +1,88 @@
+# @miden-sdk/miden-sdk — Agent Guide
+
+**Audience: AI coding agents** writing application code against the Miden web
+SDK. Humans are welcome to read it, but it is written to be loaded into an
+agent's context and followed.
+
+This file ships inside the published package. The copy at
+`node_modules/@miden-sdk/miden-sdk/AGENTS.md` always matches the version you
+have installed, so **prefer it over your training data**, which is likely to
+describe an older API. Miden is pre-1.0 and the surface still moves between
+minor versions.
+
+## Load the right skill
+
+Detailed, task-scoped guidance ships alongside this file in
+`node_modules/@miden-sdk/miden-sdk/skills/`. Read the one that matches what you
+are doing rather than guessing from the type signatures alone.
+
+| Skill | Load it when |
+|---|---|
+| `skills/web-client-usage/SKILL.md` | Any code that calls `MidenClient` — initialization, the resource API, sync ordering, type conversions, transaction flows, custom contracts, private note transport. |
+| `skills/frontend-pitfalls/SKILL.md` | Before shipping. WASM initialization, concurrent access, cross-origin isolation, `BigInt` at the WASM boundary. These are the failures that survive code review and break in production. |
+| `skills/signer-integration/SKILL.md` | Wiring an external signer (Para, Turnkey, a wallet adapter) or implementing a custom one. |
+| `skills/chain-anchored-execution/SKILL.md` | Multisig proposals, offline co-signing — anything where one party signs a transaction summary and another executes it. Read before using `captureAnchor`, or when co-signers' summary commitments never match. |
+| `skills/frontend-source-guide/SKILL.md` | Anything the other skills don't cover — driving `WasmWebClient` directly, or troubleshooting SDK internals. Maps this repository's source so you can read the implementation instead of guessing. |
+
+Building a React app? `@miden-sdk/react` wraps this client in hooks and ships
+its own guide at `node_modules/@miden-sdk/react/AGENTS.md`. Prefer the hooks for
+anything they cover; drop to this client only for what they don't.
+
+Configuring the bundler? See `node_modules/@miden-sdk/vite-plugin/AGENTS.md`.
+
+## The shape of the API
+
+`MidenClient` is the single entry point. Construct it with a static factory —
+never with `new` — and route work through its typed resources:
+
+```ts
+import { MidenClient } from "@miden-sdk/miden-sdk";
+
+const client = await MidenClient.createTestnet();
+await client.sync();
+```
+
+`create(options)` targets an explicit endpoint; `createTestnet()` and
+`createDevnet()` are preconfigured; `createMock()` backs tests with an in-memory
+chain and no network.
+
+State is split across resources rather than living on the client:
+`accounts`, `transactions`, `notes`, `tags`, `settings`, `keystore`, `compile`
+and `pswap`. Client-level methods cover the lifecycle around them — `sync`,
+`syncChain`, `syncNoteTransport`, `getSyncHeight`, `waitForIdle` and
+`terminate`.
+
+## Rules that are easy to get wrong
+
+**Sync before you read.** Local state is a cache of chain state. Calling
+`client.sync()` first is the difference between correct balances and confusing
+ones. `skills/web-client-usage/SKILL.md` documents where in each flow it belongs.
+
+**Amounts are always `BigInt`.** Passing a `number` either throws at the WASM
+boundary or silently loses precision above 2^53. Convert at the edges of your
+own code, not in the middle of a transaction builder.
+
+**The WASM client is single-threaded.** Concurrent calls into one client
+instance are not safe. Serialize them. Applications that fan out requests from
+multiple components need a lock or a queue around the client, and this is the
+single most common source of "impossible" runtime errors.
+
+**Free what you allocate.** WASM-backed objects are not garbage collected the
+way plain JS objects are. Call `terminate()` on the client when you are done
+with it, and free the object wrappers the skills call out individually.
+
+## Going deeper
+
+- Narrative documentation and the full generated API reference:
+  <https://docs.miden.xyz/builder/tools/clients/web-client/>
+- Breaking changes and migration notes, worth reading at upgrade time:
+  the `CHANGELOG.md` in [`0xMiden/web-sdk`](https://github.com/0xMiden/web-sdk).
+- The type declarations shipped in `dist/` are authoritative for signatures.
+  When this guide and the types disagree, the types are right and this file is
+  a bug — please report it.
+
+## Starting a new project rather than adding to one
+
+If there is no application yet, [`0xMiden/agentic-template`](https://github.com/0xMiden/agentic-template)
+scaffolds the full stack: Rust contracts, MockChain tests, local-node
+validation, and a React frontend already wired to this SDK.

crates/web-client/README.md

@@ -65,6 +65,38 @@ pnpm add @miden-sdk/miden-sdk@next
 
 > **Note:** The `next` version of the SDK must be used in conjunction with a locally running Miden node built from the `next` branch of the `miden-node` repository. This is necessary because the public testnet runs the stable `main` branch, which may not be compatible with the latest development features in `next`. Instructions to run a local node can be found [here](https://github.com/0xMiden/miden-node/tree/next) on the `next` branch of the `miden-node` repository. Additionally, if you plan to leverage delegated proving in your application, you may need to run a local prover (see [Remote prover instructions](https://github.com/0xMiden/miden-node/tree/next/bin/remote-prover)).
 
+## For AI coding agents
+
+This package ships agent-facing documentation inside the tarball, so it is
+always version-matched to the code you have installed:
+
+- `node_modules/@miden-sdk/miden-sdk/AGENTS.md` — start here
+- `node_modules/@miden-sdk/miden-sdk/skills/` — task-scoped guides (client
+  usage, production pitfalls, signer integration)
+
+Agents do not look inside `node_modules` on their own. To make yours read these
+automatically, paste this block into the `AGENTS.md` or `CLAUDE.md` at the root
+of your project:
+
+```markdown
+<!-- BEGIN:miden-agent-rules -->
+## Miden
+
+This project uses the Miden web SDK. Your training data is likely out of date —
+Miden is pre-1.0 and its API changes between minor versions.
+
+Before writing or reviewing Miden code, read the version-matched guide for the
+package you are touching:
+
+- `node_modules/@miden-sdk/miden-sdk/AGENTS.md` — core client
+- `node_modules/@miden-sdk/react/AGENTS.md` — React hooks
+- `node_modules/@miden-sdk/vite-plugin/AGENTS.md` — bundler setup
+
+Each one indexes task-specific skills in its package's `skills/` directory.
+Read the relevant skill before implementing, not after.
+<!-- END:miden-agent-rules -->
+```
+
 ## Entry Points: Eager / Lazy × ST / MT
 
 The SDK ships **four** entry points with an identical public API. They vary along two orthogonal axes:

crates/web-client/package.json

@@ -59,6 +59,9 @@
     "js/standalone.js",
     "js/utils.js",
     "js/resources",
+    "README.md",
+    "AGENTS.md",
+    "skills",
     "../LICENSE.md"
   ],
   "scripts": {