docs: fill the Start here and Understand trees and make the corpus executable by robrigo · Pull Request #11 · atomicassets/atomic-knowledge

robrigo · 2026-08-18T18:05:35Z

Why

The site's navigation has declared Start here and Understand since the relaunch, and both groups render empty because the corpus had no tutorials and no concepts. This pull request fills the two trees and makes the corpus executable: the first-collection tutorial walks from a faucet account to a minted asset with a checkpoint after every step, and every step of it was executed against WAX testnet before it was written down (the faucet answers, creates the account with 8192 bytes of RAM and no tokens, and get_token transfers 500 WAX, not the 100 its page advertises); six concepts pages explain why the protocol is shaped the way it is, including the comparison against the EVM single-token standard and the royalty explainer; five clone-and-run starters (two keyless reads, three WAX testnet signers behind the WAX_TESTNET_ACTOR and WAX_TESTNET_PRIVATE_KEY contract, forty tests) land under starters/ with the CI arm that runs them, read-only on every event and signing only on push and the weekly schedule; and five Mermaid diagrams draw the flows whose ordering prose states worst. The starters land first in the series so the tutorial's links resolve at every commit.

Writing the pages against the live chain surfaced five wrong claims in the draft content and two in existing reference pages; the drafts are corrected here, and the two reference corrections (the WAX mainnet bonus fee is 1 percent to eco.atomic, not 2 percent to wax; the 100-row cap does not bind every list route) are follow-ups because their pages are graded in the ledger.

Notes for the maintainer

Stacked on the agent-path pull request. The signing starters were verified as composed actions only; no transaction was signed in authoring. The write arm runs each starter's entrypoint in order under the wax-testnet environment, and every push to main mints throwaway rows on the testnet account with nothing reclaiming the RAM; say so if you want reuse-and-cleanup instead. The listing starter carries no zero-price guard, because the sales guide places that on the chain side of the line the SDK helpers hold. The commits are unsigned; the squash merge carries GitHub's signature.

Copilot

Pull request overview

This PR fills the previously empty “Start here” and “Understand” navigation trees by adding an end-to-end WAX testnet tutorial, a set of runnable “starter” packages (read-only and signing flows), and several concepts pages that explain key protocol/market design constraints. It also makes the new starter corpus executable in CI and adds Mermaid diagrams to clarify core flows.

Changes:

Add two tutorials: a “clone-and-run starters” index and a step-by-step “first minted asset on WAX testnet” walkthrough.
Introduce starter Node packages under starters/ (read assets, read storefront sales, create collection, mint, list sale) with runnable tests and fixtures.
Add new concepts pages and Mermaid diagrams; update repo routing (AGENTS.md), markdownlint ignore globs, and CI workflow to execute starter tests.

Reviewed changes

Copilot reviewed 58 out of 63 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
`tutorials/starters.md`	Adds a “Starters” index page describing the runnable starter directories and their prerequisites.
`tutorials/first-collection.md`	Adds a step-by-step tutorial from testnet account creation through minting an asset, with chain/API checkpoints.
`starters/storefront-read/test/storefront-read.test.js`	Adds tests for the storefront sales reader (live read shape + offline fixture assertions).
`starters/storefront-read/test/sale-row.fixture.json`	Adds captured AtomicMarket sale-row fixture used by offline tests.
`starters/storefront-read/src/sales.js`	Implements sale reading/summarization and terminal-safe formatting helpers.
`starters/storefront-read/src/index.js`	CLI entrypoint that prints live sales for a collection on WAX mainnet.
`starters/storefront-read/README.md`	Documents the storefront-read starter usage, behavior, tests, and residual risk.
`starters/storefront-read/package.json`	Defines the storefront-read starter package and its dependency on `@atomichub/atomicmarket`.
`starters/storefront-read/package-lock.json`	Locks dependencies for the storefront-read starter.
`starters/storefront-read/LICENSE`	Adds MIT license for the storefront-read starter.
`starters/storefront-read/.gitignore`	Ignores `node_modules/` for the storefront-read starter.
`starters/read-assets/test/read-assets.test.js`	Adds tests for the assets reader (live read shape + offline fixture assertions).
`starters/read-assets/test/asset-row.fixture.json`	Adds captured AtomicAssets asset-row fixture used by offline tests.
`starters/read-assets/src/index.js`	CLI entrypoint that prints assets held by a WAX mainnet account.
`starters/read-assets/src/assets.js`	Implements asset reading/summarization and terminal-safe formatting helpers.
`starters/read-assets/README.md`	Documents the read-assets starter usage, behavior, tests, and residual risk.
`starters/read-assets/package.json`	Defines the read-assets starter package and its dependency on `@atomichub/atomicassets`.
`starters/read-assets/package-lock.json`	Locks dependencies for the read-assets starter.
`starters/read-assets/LICENSE`	Adds MIT license for the read-assets starter.
`starters/read-assets/.gitignore`	Ignores `node_modules/` for the read-assets starter.
`starters/mint-asset/test/mint-asset.test.js`	Adds tests for minting logic and skip-path behavior without credentials.
`starters/mint-asset/src/session.js`	Creates a WharfKit session for WAX testnet signing.
`starters/mint-asset/src/mint.js`	Composes `createschema` + `mintasset`, derives schema name entropy, and reads back minted asset.
`starters/mint-asset/src/index.js`	CLI entrypoint that signs on WAX testnet and polls the API until the minted asset appears.
`starters/mint-asset/src/credentials.js`	Implements shared “missing credentials => exit 0 with message” behavior for signing starters.
`starters/mint-asset/README.md`	Documents mint-asset usage, environment contract, signing flow, tests, and residual risk.
`starters/mint-asset/package.json`	Defines the mint-asset starter package and dependencies (AtomicAssets + WharfKit session/privatekey).
`starters/mint-asset/package-lock.json`	Locks dependencies for the mint-asset starter.
`starters/mint-asset/LICENSE`	Adds MIT license for the mint-asset starter.
`starters/mint-asset/.gitignore`	Ignores `node_modules/` for the mint-asset starter.
`starters/list-a-sale/test/list-a-sale.test.js`	Adds tests for the listing composer and skip-path behavior without credentials.
`starters/list-a-sale/src/session.js`	Creates a WharfKit session for WAX testnet signing.
`starters/list-a-sale/src/listing.js`	Composes the AtomicMarket V2 listing pair and reads back the listed sale.
`starters/list-a-sale/src/index.js`	CLI entrypoint that signs a listing on WAX testnet and polls until the sale is indexed.
`starters/list-a-sale/src/credentials.js`	Implements shared “missing credentials => exit 0 with message” behavior for signing starters.
`starters/list-a-sale/README.md`	Documents list-a-sale usage, environment contract, composed actions, tests, and residual risk.
`starters/list-a-sale/package.json`	Defines the list-a-sale starter package and dependencies (AtomicAssets + AtomicMarket + WharfKit).
`starters/list-a-sale/package-lock.json`	Locks dependencies for the list-a-sale starter.
`starters/list-a-sale/LICENSE`	Adds MIT license for the list-a-sale starter.
`starters/list-a-sale/.gitignore`	Ignores `node_modules/` for the list-a-sale starter.
`starters/create-collection/test/create-collection.test.js`	Adds tests for collection-name derivation, skip behavior, and action composition.
`starters/create-collection/src/session.js`	Creates a WharfKit session for WAX testnet signing.
`starters/create-collection/src/index.js`	CLI entrypoint that signs `createcol` on WAX testnet and polls until the collection is indexed.
`starters/create-collection/src/credentials.js`	Implements shared “missing credentials => exit 0 with message” behavior for signing starters.
`starters/create-collection/src/collection.js`	Derives collection name, composes `createcol`, and reads the collection back via the testnet API.
`starters/create-collection/README.md`	Documents create-collection usage, environment contract, signing flow, tests, and residual risk.
`starters/create-collection/package.json`	Defines the create-collection starter package and dependencies (AtomicAssets + WharfKit).
`starters/create-collection/package-lock.json`	Locks dependencies for the create-collection starter.
`starters/create-collection/LICENSE`	Adds MIT license for the create-collection starter.
`starters/create-collection/.gitignore`	Ignores `node_modules/` for the create-collection starter.
`reference/atomicmarket/fees-and-royalties.md`	Adds a Mermaid diagram illustrating settlement fee deductions and royalty split conceptually.
`reference/atomicassets/structure.md`	Adds a Mermaid diagram depicting the four-level AtomicAssets model and relationships.
`guides/sales.md`	Adds a Mermaid diagram showing the sale lifecycle flow and where assets/tokens move.
`guides/auctions.md`	Adds a Mermaid state diagram for the auction lifecycle and transitions.
`concepts/royalties.md`	Adds a concepts page explaining royalties as on-chain settlement math and where to read payout logs.
`concepts/reading-atomic-data.md`	Adds a concepts page comparing chain reads vs hosted API reads and their tradeoffs.
`concepts/ownership-on-chain.md`	Adds a concepts page explaining ownership as table scope and the “media is a reference” caveat.
`concepts/one-order-book.md`	Adds a concepts page explaining why listings land in one contract and how marketplaces still earn fees.
`concepts/four-level-model.md`	Adds a concepts page explaining why AtomicAssets splits data across four levels and what each owns.
`concepts/compared-with-erc721.md`	Adds a concepts page comparing AtomicAssets mechanics with ERC-721/metadata and royalty behaviors.
`AGENTS.md`	Updates the routing table to include the new tutorials and concepts pages for navigation/outcome routing.
`.markdownlint-cli2.jsonc`	Updates ignore globs to avoid linting locally-installed starter `node_modules` trees.
`.github/workflows/checks.yml`	Updates CI to run every starter’s tests without keys on all events, and run signing starters in order on push/schedule.

Files not reviewed (5)

starters/create-collection/package-lock.json: Generated file
starters/list-a-sale/package-lock.json: Generated file
starters/mint-asset/package-lock.json: Generated file
starters/read-assets/package-lock.json: Generated file
starters/storefront-read/package-lock.json: Generated file

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

+
+Every step is written out. Where a value could be anything, this page picks one, so there is no choice to make and no branch to get wrong. The [starters](starters.md) are the same code as directories you can clone.
+
+You need Node 22 or newer and `curl`. You do not need an API key: reading AtomicAssets state takes no credential, no account, and no registration, which is why every checkpoint below is a plain `curl` (see [Build a session and sign](../guides/signing.md#reads-need-no-key-no-account-and-no-registration), "Reads need no key, no account, and no registration").


+ * @property {string} assetId the listed asset, or null when the row lists none
+ * @property {string} assetName


+ * @property {string} name asset name, or null when the asset carries none
+ * @property {string} collection
+ * @property {{name: string, value: unknown}} attribute first attribute, or null


Every page here describes a call and none of them is executable, so a reader who wants to know whether the corpus is right has to build the harness first. Five directories now sit under starters/, each cloned and run on its own: two read the hosted API with no key at all, and three sign on WAX testnet, where the V2 contracts run. The two signing variables are the contract the whole set turns on. WAX_TESTNET_ACTOR and WAX_TESTNET_PRIVATE_KEY are spelled that way in every starter, every README, and the workflow environment, and a starter missing either prints which one it wanted, signs nothing, and exits zero. A clone with no keys therefore runs green and says why instead of failing at a signature nobody asked for. The residual risk is stated rather than engineered away. The key signs on a chain with no value and the collections are disposable, so the worst case is junk minted into a throwaway collection, and the configuration that leaks is a repository secret without a fork guard. The lint ignore widens with them. Each starter installs into its own node_modules, and a top-level-only ignore would put every dependency's README under the corpus rule set the moment a contributor runs the tool.

The starters job was a stub that skipped itself while the directory did not exist. It now runs, in two arms split by what they hold rather than by what they do. The first arm runs every starter's tests on every event, with no key in scope at all. That is what lets a fork pull request exercise the live reads and the skip paths without the workflow handing it anything sensitive. The second arm executes the three signing starters against WAX testnet, because a starter proved only by its own tests rots the moment an endpoint or a contract moves under it, and live execution is the only thing that catches that. The event test is the fork guard. A fork reaches this workflow only through pull_request, so excluding that event excludes every fork, and it also keeps signing off the pull-request path, where a flaky endpoint would train a reader to ignore a red check. The three run in a fixed order because each needs what the one before it wrote.

The corpus documented every action and no route through them. A reader who arrived wanting to mint something had to assemble the order from four reference pages and a guide, and the site's Start here group rendered empty because the pin carried nothing to fill it. The tutorial charter is one guaranteed-success path with no decision in it, so every value the reader could have chosen is picked here and every step ends in a read that says whether it worked. The failure appendix carries the messages a first run actually produces, each traced to the page that documents the behavior behind it. The path runs on WAX testnet because that is where V2 is deployed, and its one external dependency is the public faucet the first step names. Account creation and funding are two separate faucet calls, which is why the tutorial spends a step on each.

Reference says what is true and guides say how to do a named task. Neither says why the protocol is shaped the way it is, so a reader who wanted to decide whether to build on it had to infer the design from field lists. The site declares an Understand group for exactly this and it rendered empty. Each page explains one shape and links the reference page that validated every fact it leans on, which is why none of them carries a validation tier or a ledger row: a concepts page restates, and the page it restates is the one graded. Two of the six exist because an integrator arrives holding a different mental model. The comparison against the EVM single-token standard answers the question that gets asked first, and the royalty page answers the one that gets asked next, which is whether a resale royalty is a request a storefront can decline.

Eight pages landed with no row in the routing table, so an agent reading this file could reach none of them and would go on inferring a mint order from the reference tree. Each new row sits beside the reference page it hands off to, because that is where an agent already stops. The ledger sentence gains the reason the two trees take no row in it. Without that, the validation-consistency job's silence on an ungraded tutorial reads as a gap rather than as the design.

Four pages open on a multi-step contract sequence a reader has to reassemble from paragraphs before any of the detail below means anything: which state an auction is in, what a sale row does before an asset moves, what a settlement subtracts and in what order, and how the four data levels hang together. A Mermaid fence renders natively on GitHub and through rehype-mermaid on the site, so one source serves both surfaces with no binary asset and the diagram stays inside the fidelity gate that already compares fenced blocks byte for byte. Labels are plain corpus prose for the same reason: they are read by the banned-term and casing rules once the site renders them into SVG text. The four-level diagram is the concepts page's, mirrored here so the reference opens on the same picture the explainer taught.

robrigo deployed to wax-testnet August 18, 2026 18:05 — with GitHub Actions Active

robrigo requested a lite review from Copilot August 18, 2026 18:05

Copilot started reviewing on behalf of robrigo August 18, 2026 18:06 View session

robrigo force-pushed the docs/agent-path branch from 7c415f7 to e178f20 Compare August 18, 2026 18:08

robrigo force-pushed the docs/tutorials-and-concepts branch from 88baa65 to a0b1915 Compare August 18, 2026 18:09

robrigo deployed to wax-testnet August 18, 2026 18:09 — with GitHub Actions Active

Copilot AI reviewed Aug 18, 2026

View reviewed changes

robrigo changed the base branch from docs/agent-path to main August 18, 2026 19:58

robrigo added 6 commits August 18, 2026 16:09

robrigo force-pushed the docs/tutorials-and-concepts branch from a0b1915 to d328795 Compare August 18, 2026 20:09

robrigo deployed to wax-testnet August 18, 2026 20:09 — with GitHub Actions Active

robrigo merged commit 3b69e50 into main Aug 18, 2026
10 checks passed

robrigo deleted the docs/tutorials-and-concepts branch August 18, 2026 20:09

Navigation Menu

Uh oh!

docs: fill the Start here and Understand trees and make the corpus executable - #11

docs: fill the Start here and Understand trees and make the corpus executable#11
robrigo merged 6 commits into
mainfrom
docs/tutorials-and-concepts

robrigo commented Aug 18, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants


		Every step is written out. Where a value could be anything, this page picks one, so there is no choice to make and no branch to get wrong. The [starters](starters.md) are the same code as directories you can clone.

		You need Node 22 or newer and `curl`. You do not need an API key: reading AtomicAssets state takes no credential, no account, and no registration, which is why every checkpoint below is a plain `curl` (see [Build a session and sign](../guides/signing.md#reads-need-no-key-no-account-and-no-registration), "Reads need no key, no account, and no registration").

		* @property {string} assetId the listed asset, or null when the row lists none
		* @property {string} assetName

Uh oh!

Conversation

robrigo commented Aug 18, 2026

Why

Notes for the maintainer

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants