docs: give an agent the path from a read to a signed testnet write - #10
Merged
Conversation
There was a problem hiding this comment.
Pull request overview
This PR improves the documentation “write path” by introducing a dedicated signing/session guide and updating existing write-oriented guides and SDK docs to link to it, while also reorganizing agent routing to be outcome-based and expanding the integration/report skills to carry more actionable procedure.
Changes:
- Added
guides/signing.mdto standardize how a WharfKitSessionis constructed (installs, chain IDs, identity/auth model, and V2 network guidance). - Updated multiple guides and the AtomicAssets SDK reference to link to the new signing guide where
sessionis first referenced. - Reworked
AGENTS.mdrouting by outcome and updated skills/docs metadata and validation logging to reflect the new material and pins.
Reviewed changes
Copilot reviewed 14 out of 14 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
validation-log.md |
Records the new signer-library pin and adds validation coverage for the new signing guide. |
skills/report/SKILL.md |
Expands the difficulty report schema to match issue-form fields more closely. |
skills/atomic-integration/SKILL.md |
Replaces pure routing with concrete integration procedures (network choice, mint flow, market composers). |
reference/sdk/atomicassets.md |
Links SDK-produced actions to the new session/signing guide for a complete write flow. |
guides/signing.md |
New guide defining session construction, chain IDs, identity shape, and read-vs-write credential expectations. |
guides/sales.md |
Links sale write snippets to the signing/session construction guide. |
guides/offers.md |
Links offer write snippets to the signing/session construction guide. |
guides/links.md |
Links claim-link write snippets to the signing/session construction guide. |
guides/deposits.md |
Links deposit write snippet to the signing/session construction guide. |
guides/buyoffers.md |
Links buyoffer write snippets to the signing/session construction guide. |
guides/auctions.md |
Links auction write snippets to the signing/session construction guide. |
guides/asset-lifecycle.md |
Links asset lifecycle write snippets to the signing/session construction guide. |
CLAUDE.md |
Reduces the entry point to a single pointer to AGENTS.md. |
AGENTS.md |
Replaces domain routing with outcome-based routing and clarifies version-pin recheck expectations. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| [Freeform body] | ||
| ``` | ||
|
|
||
| The first five fields are the atomic-knowledge issue forms, field for field, so a maintainer opens an issue by pasting one finding across rather than re-deriving it. A `doc-error` or `doc-misleading` finding fills the fact-error form; a `doc-gap` or `design-pattern` finding fills the missing-fact form. The last three fields have no form field and stay in the report. |
Contributor
Author
There was a problem hiding this comment.
Fixed in the amended commit: the sentence now names the five fields from page through contract-version and says the category picks the form, so the count and the mapping agree with the two issue forms.
Comment on lines
+42
to
+47
| const session = new Session({ | ||
| actor: process.env.WAX_TESTNET_ACTOR, | ||
| permission: 'active', | ||
| chain: Chains.WAXTestnet, | ||
| walletPlugin: new WalletPluginPrivateKey(process.env.WAX_TESTNET_PRIVATE_KEY), | ||
| }) |
Contributor
Author
There was a problem hiding this comment.
Fixed in the amended commit: the snippet reads both variables into locals and throws with the exact message when either is undefined, so it compiles under strict TypeScript and fails fast at run time, matching the starters' environment contract.
robrigo
force-pushed
the
docs/agent-path
branch
from
August 18, 2026 18:08
7c415f7 to
e178f20
Compare
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 14 out of 14 changed files in this pull request and generated no new comments.
Suppressed comments (1)
guides/offers.md:11
- The text says asset IDs require the string treatment, but the JSON example below uses a numeric
recipient_asset_idsvalue. This is internally inconsistent and may mislead readers into mixing representations; it’s clearer to keep all asset IDs as strings in examples.
Each action's data shape is plain JSON first, then the same call through `@wharfkit/session`'s `session.transact()`, which [Build a session and sign](signing.md) constructs. Only asset ids need the string treatment: see [AtomicMarket V2 changes](../reference/atomicmarket/v2-changes.md#large-integers-serialize-as-strings) ("Large integers serialize as strings") for why. `template_id` is an `int32_t`, and offer ids are a small contract-wide `uint64` counter (a live `offers` row reads `offer_id: 7`); both stay well inside the safe-integer range and serialize as bare JSON numbers, as the numeric `offer_id` examples below do. See [@wharfkit/antelope client behavior](../reference/wharfkit.md).
Every write snippet in this corpus opened against a session that no page constructed, and the corpus stated no chain id anywhere, so a reader could produce a working read and could not plan a testnet mint. The signer page closes both gaps: the two install lines, the session constructor with its two identity branches, the actor and permission pair, and one chain id per chain, each read live from a running node and cross-checked against the pinned library constants. Each guide that opens a snippet against a session now says where that session comes from, so the construction arrives before the first transact call rather than never.
The routing table answered "which document covers this subject" while an agent arrives holding an outcome, so "mint an asset on testnet" resolved only by inference across three pages. Each row is now an outcome and the one page that serves it, ordered the way an integration meets them. The reading rules also name the pins a version-sensitive fact has to be re-checked against. The instruction to re-check such facts was already there and gave the reader nothing to check against.
Six of its lines were content and three of those restated AGENTS.md, so a vendor-named file at the root of a neutral protocol corpus held a second copy of rules that drift apart the moment one side is edited.
The skill cost a load to say "see AGENTS.md", which is the file the caller had just read. It now carries what a routing table cannot: the five-step mint with the RAM payer that bills the minter rather than the recipient, the five market composers with their memo literals and the last-offer placement rule, the two bundle opt-outs that guard the caller error which commits instead of reverting, and what a settlement quantity has to be. The network choice leads, because reaching for mainnet first is the one mistake here that costs real assets.
A difficulty report and a fact-error issue asked for the same evidence in two different shapes, so filing the issue meant re-deriving the report. An entry now opens with the five fields both issue forms declare, in their order, and the report-only fields follow, which lets a maintainer paste one finding across instead of rewriting it. The field list becomes a table. A uniform run of label-and-colon bullets was already imitating one, and the body guidance stops asking for the quote and the observation the fields now hold.
robrigo
force-pushed
the
docs/agent-path
branch
from
August 18, 2026 20:08
e178f20 to
2a84497
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
An agent handed only the mirrors could produce a working read and could not plan a testnet write: every write snippet opened against a session no page constructed, no page carried a chain id or the signing-library install lines, the auth model was never stated in one line, and
AGENTS.mdrouted by document rather than by the outcome an agent arrives with. This pull request adds the signer guide (session construction with@wharfkit/session, the chain-id table probed live on every listed network, the account and permission shape, the one-line auth model, and the V2 sentence), links each write snippet to it where the reader first meetssession, rewritesAGENTS.mdto route by outcome with the two SDK pins stated where it tells an agent to re-check version-pinned facts, gives the integration skill the mint flow, the composer rules, and the network choice instead of one indirection, aligns the report skill's fields with the issue forms that receive them, and reducesCLAUDE.mdto the pointer it is.Notes for the maintainer
Stacked on the SDK-accuracy pull request. Every check ran locally at each commit in the series. The signing-library pin (
@wharfkit/session1.6.1) is new and recorded in the ledger. The commits are unsigned; the squash merge carries GitHub's signature.