feat(docs): getting started for agents

[nour-karoui]

Self-service Getting Started for agents & humans on the Labs API — IP-3028.

Makes the API Reference self-service: a reader — or an agent — with only the docs URL and a mol_ credential can get to a lab with files in it.

What's new

• api-reference/getting-started/ — "choose your path" for the four lanes, prerequisites with real costs, a ≤10-minute quickstart, and four tutorials: public upload, encrypted upload, agent-as-Contributor on a lab made in the app, announce. Plus an agent one-pager meant to be pasted into a system prompt.
• Publishes what used to be "contact the team": both x402 gateway base URLs, the staging-introspection route to the schema, the USDC faucet. Only the credential request remains.
• Removes the Assignment Agreement from all of api-reference/; legal-agreements.md is hidden and out of nav.
• Corrects the sign-in flow for the IP-3013 single-use nonce, the Authorization: Bearer contradictions, the "service tokens are lab-scoped" error, broken anchors, and the error contract.
• Adds a table comparing the three wallets an integration juggles — owner, agent, and the Lab's OCL account — including which API field each address belongs in (requested by Logan).
• Deletes api-reference/IPNFT-api.md, an orphan duplicate teaching the retired x-api-key.

Verified against staging

All four tutorials run end to end; 120/120 embedded GraphQL documents validate against the live schema; 0 broken links. Evidence: lab lab-1542, [mint tx]((https://sepolia.basescan.org/tx/0x65c63576e1ccbf90e86de9f21ea2785a865fba7b64b99e48699e2fb422635c82), public datasetId did:odf:fed01750c84c6aba2f13fda72de412cb858d034b3b2dc76a388f5e58fbe09c7a11474, encrypted did:odf:fed01e35ce981a01fdfc57d037252bdf3bcf2775e0bb47b0a8222d851d3d0f735cacf with a verified decrypt round trip. Tutorial 3 verified post-IP-3013 on testing-lab: an agent wallet granted Contributor in the app self-issued a token and uploaded into a lab it does not own.

[0xmme]

I think we could format this also as a code block, similar to staging.

[0xmme]

As announcements are somewhat deprecated or at least not shown anymore, I guess we should not highlight it anymore.

[0xmme]

same here, I think we shouldn't mention announcements any longer.

[0xmme]

I guess we could just remove this page to keep our docs slim. It was published recently as a quick explanation for an agentic presentation by the product team and shouldn't have a big audience.

[ph0ph0]

I don't think this reads well and is slightly confusing. I would change this to:

"The lanes are composable, so choosing one now doesn't lock you in to that lane only."

[ph0ph0]

The second part of this line reads more like a review of the docs rather than an instruction. Change:

"There is no self-service issuance yet, so this is the single "ask the team" left in the API docs."

To:

"There is no self-service issuance yet (coming soon), so you will need to request this from the Molecule team."

[ph0ph0]

Change:

"| [Tutorial 1] ..."

To:

"| [Public File Upload Tutorial] ..."

[ph0ph0]

Change:

"| [Tutorial 3] ..."

To:

"| [Agent Access Tutorial] ..."

[ph0ph0]

Remove "verified 2026-08-27 by eth_call"

Change to:

"""
| LabNFT mint | Gas only on Base Sepolia and on Base mainnet | Read it live yourself using mintFeeWei(), and if non-zero, send it as value |
"""

[ph0ph0]

Change:

"Quoted per request in the 402 challenge — $0.01 USDC on both environments today"

To:

"Quoted per request in the 402 challenge, currently $0.01 USDC on both environments "

[ph0ph0]

This is unclear and poorly written, improve the wording:

eg:

"Onchain and offchain systems that work in parallel must be synchronised, and therefore there can be delays in data propagation. This means that a successful response does not mean that every downstream read has caught up yet"

[ph0ph0]

What is this section and why is it here? It is unclear why this is relevant to the reader. It's important to imagine that the reader has zero knowledge of how Mol API works or why they are doing each action

[ph0ph0]

Review from my agent - please ask your agent to double check that they are valid and if so, fix them:

Issue 1 — WALLET_MISMATCH documented as a sign-in failure the resolver can never return (high)

Where:

• api-reference/getting-started/create-lab-and-upload-file.md:103
• api-reference/labs-api/service-tokens.md:111
• api-reference/changelog.md:22
• .github/prompts/docs-sync.md:68

Issue: All four state that generateServiceToken returns UNAUTHENTICATED / reason: WALLET_MISMATCH when "walletAddress isn't the signer". The resolver (desci-infra
lambda/appsync-resolver-labs-lambda/index.ts, signature path) emits exactly three reasons: NONCE_NOT_FOUND, NONCE_EXPIRED, INVALID_SIGNATURE. A wrong walletAddress recomposes the
sign-in message for the claimed address, verifyMessage fails, and the caller gets INVALID_SIGNATURE. WALLET_MISMATCH exists only in the legal-agreement resolvers' Privy-user
path (x-wallet-address header vs. the wallet named in the call). The commit's own "9/9 staging checks" never probed wallet-mismatch — because it's unreachable.

Why it matters: An agent that hits the wrong-address case gets INVALID_SIGNATURE, whose documented fix ("sign the most recent message byte-for-byte") never says to check the
address — while the branch that would have can never fire. And docs-sync.md:68 instructs the sync agent that these reasons "come from the generateServiceToken resolver", baking
the error into the source-of-truth map.

Fix: Delete the WALLET_MISMATCH rows from the three sign-in tables; fold the case into INVALID_SIGNATURE ("altered text, a superseded message, or a walletAddress that is not the
signer"). Drop it from docs-sync.md:68's list. Keep changelog.md:125's general catalogue row — the reason genuinely exists on the legal-agreement path.

---

Issue 2 — Bad expiresIn documented as VALIDATION_FAILED; it actually returns a retryable-looking INTERNAL_ERROR (medium-high)

Where:

• api-reference/getting-started/create-lab-and-upload-file.md:104
• api-reference/labs-api/service-tokens.md:100 and :113
• api-reference/authentication.md:154

Issue: expiresIn is never validated in the resolver — it flows into token-manager-service.generateServiceToken, where calculateExpirationDate (lib/utils/token-expiration.ts)
throws a plain Error on bad format or out-of-bounds values. The service's own catch wraps it with maskedErrorResult(..., { reason: "TOKEN_GENERATION_FAILED" }), and
classifyError's generic-Error fallback yields INTERNAL_ERROR with a masked message. So "3y" comes back as INTERNAL_ERROR / reason: TOKEN_GENERATION_FAILED — not
VALIDATION_FAILED.

Why it matters: The agent one-pager (correctly) classifies INTERNAL_ERROR as retryable, so an agent following these docs will retry a permanently-failing request with backoff
instead of fixing its input — the exact failure loop the error contract exists to prevent. It also means "our fault, file a bug" masking is hiding a client mistake — arguably a
backend bug worth its own ticket (validateExpirationFormat exists in the backend and is unused in this path).

Fix: Either fix the backend first (pre-validate expiresIn in the resolver) and keep the docs as-written, or correct the four doc sites to today's behavior. Given the webinar
deadline: correct the docs now ("today this surfaces as INTERNAL_ERROR / reason: TOKEN_GENERATION_FAILED; validate the format client-side") and file the backend ticket.

---

Issue 3 — reason: NOT_CONTRIBUTOR doesn't exist (medium)

Where: api-reference/getting-started/agent-as-a-lab-contributor.md:136

Issue: The indexer-lag hint says a pre-index write returns UNAUTHORIZED (reason: NOT_CONTRIBUTOR). That reason string appears nowhere in the backend — a membership denial is
code: UNAUTHORIZED with details.reason: "UNAUTHORIZED" (auth-service.ts's MembershipAuthReason map → membershipDenialApiError). The retry helper matches on the code, so the
script works; only the parenthetical is fiction — but it's exactly the kind of specific-looking token an agent will grep responses for. (Note: changelog.md:126 also lists
NOT_CONTRIBUTOR as an example reason under UNAUTHORIZED — same correction applies there.)

---

Issue 4 — example-workflow.md deleted with no redirect; the PR built the right stub and then deleted it (medium)

Where: commit 7b50197 deleted api-reference/labs-api/example-workflow.md; the repo still has no .gitbook.yaml at head 4974fda.

Issue: Example Workflow has been the published, SUMMARY-listed tutorial URL for months — the page external bookmarks, chat links and search results point at. An earlier commit in
this PR replaced it with a hidden "This page moved" stub (the correct GitBook pattern); a later commit deleted the stub, so the live URL will 404 after merge. GitBook Git-sync
does not auto-redirect removed pages. (IPNFT-api.md's deletion is fine — never in SUMMARY, so no published URL.)

Fix: Restore the 20-line hidden stub (now pointing at the renamed tutorial files), or add a .gitbook.yaml with redirects: { api-reference/labs-api/example-workflow:
api-reference/getting-started/README.md }.

---

Issue 5 — The oclId diagram is 6 hex chars short (low)

Where: api-reference/authentication.md:195

Issue: tokenId is an 80-bit field (ocl-id.ts: (id >> 160n) & ((1n << 80n) - 1n)), i.e. 20 hex chars. The diagram shows a 14-char field, so the pictured "oclId" is 58 hex chars —
an invalid 29-byte value on a page whose whole point is byte-level precision. The decoded values (1526, the trailing address) are right.

Pasteable comment:

▎ The tokenId field in this diagram is 14 hex chars, but it's an 80-bit field (ocl-id.ts: (id >> 160n) & ((1n << 80n) - 1n)) — 20 hex chars, making the full oclId 64. As drawn
▎ the example is a 58-char/29-byte value that validateOclId would reject. Should read 000000000000000005f6 for 1526.

---

Issue 6 — The announcements purge documents an API smaller than the live one, with no deprecation notice anywhere (medium-high, new in the last six commits)

Where:

• api-reference/labs-api/browse-and-search.md — the labActivity, activities, and searchLabs sections
• api-reference/x402-gateway.md:52-59 — endpoints table vs. the "single source of truth" sentence
• The absence: "announcement" now appears zero times across api-reference/ and release-notes/

Issue: I checked the current dev schema and gateway: createAnnouncement is still a live mutation, LabEventAnnouncement is still in the LabActivityNode union,
SearchLabsAnnouncementHit is still in SearchLabsHit, the ANNOUNCEMENT filter enum value still exists, and X402_WRITE_MUTATIONS still allow-lists createAnnouncement. Three
consequences:

• labActivity is now described as "the file-event timeline", but unfiltered it still returns announcement nodes — including ones this very PR's Tutorial 4 verification created on
  staging. The docs simultaneously deleted the filter parameter documentation, which was the actual mechanism for getting the file-only feed the page now claims is the default.
  Same for searchLabs, whose union is documented with one arm out of two — agents doing exhaustive union handling will hit typenames the docs never mention.
• x402-gateway.md:59 still says "The allow-list above is the single source of truth in X402_WRITE_MUTATIONS" — directly above a table that now silently omits one of that
  constant's six entries. The page contradicts itself.
• The previous commit's promise ("retained as a reference for integrations that already use it") was reversed: tutorial-4 deleted, files.md's Create Announcement section deleted
  — so a mutation that still works, and that these docs taught until this PR, now has zero documentation and zero deprecation notice, while the changelog's error-contract section
  promises changes are "published on this page".

Fix: Distinguish "stop recommending" from "deny existence": one deprecation entry in the changelog, restore the filter parameter row on browse-and-search with deprecation
framing, and either mark the x402 table row deprecated or file the desci-infra change removing createAnnouncement from X402_WRITE_MUTATIONS so the "single source of truth"
sentence becomes true again.

---

Issue 7 — Dated historical records were rewritten to be false (medium, new)

Where:

• api-reference/changelog.md:38 — the IP-3013 role-parity entry
• api-reference/changelog.md ~190-198 — the V2-rename/migration tables
• release-notes/labs-api.md:17-20 — entry dated 2026-08-25

Issue: The role-parity entry now reads "The five content-write mutations" — the shipped change covered six, and createAnnouncement still gates a service token on Contributor
today (verified against the resolver gates). The V2 tables dropped the createAnnouncementV2 → createAnnouncement and projectAnnouncementsV2 → labActivity/activities (filter:
ANNOUNCEMENT) rows — a legacy integrator's only documented migration path. And a release note explicitly dated 2026-08-25 was edited to remove createAnnouncement from the list of
mutations the Assignment Agreement gate applied to, which it did. A changelog that retroactively changes what shipped is worse than one mentioning a deprecated feature — it's
the reference integrators check when old code breaks.

Fix: Restore the accurate lists and rows, annotated "(announcements since deprecated — see [entry])" rather than deleted. History entries state what was true at their date.

---

Issue 8 — docs-sync.md's README row describes date stamps that no longer exist (low, new)

Where: .github/prompts/docs-sync.md:56 vs. the refactored api-reference/getting-started/README.md cost table (~line 100).

Issue: The docs-sync row says the README's live values (mintFeeWei() readings, x402 prices) are "each stamped with the date it was checked" — the refactor removed those stamps
("verified 2026-08-27 by eth_call" and the price's as-of date are gone). The stamps were also the guard that row relies on ("never update one of those from a diff alone").

Pasteable comment:

▎ Small consistency catch: docs-sync.md's README row still says the live values here are "each stamped with the date it was checked", but this refactor dropped the stamps from
▎ the cost table (mintFeeWei() no longer says "verified 2026-08-27 by eth_call", the $0.01 lost its as-of date). Either restore the dates — they're also what makes "flag, don't
▎ edit from a diff" enforceable — or update the docs-sync row.

---

[ph0ph0]

This is just a general comment and not something i would like you to change right now as it will require an internal decision. When we have agreed with Kevin/Ella, we can create a new PR for this:

We don't mention which channel to post the request in, and the request doesn't tag anyone on Discord - this will probs cause requests to go unnoticed...

We need to discuss this internally, perhaps we have a dedicated channel or at least someone who should be tagged in the request so we don't miss any.

We should have self-service ready by EOY, so hopefully we won't need this for long.

[nour-karoui]

I will mention this to ella.

[ph0ph0]

This is incorrect, a Lab page is never reachable by appending the oclId.

Before the user renames the lab, the url should be appended with lab-<tokenId>. Once the lab has been renamed, lab-<tokenId> will stop resolving.

[ph0ph0]

See my comment in Getting Started. This isn't true as it defaults to lab-<tokenId>

[ph0ph0]

We can remove the "...but one mint took over four minutes..."

Change this:

"So wrap the first call in withIndexerLagRetry. On staging the record usually appears within seconds, but one mint took over four minutes, which is why the helper keeps retrying that long instead of giving up after a few seconds."

To something like:

"Wrap the first call in withIndexerLagRetry so the helper will retry until the record arrives."

[ph0ph0]

Please merge once changes are made, and ensure that all my previous comments are resolved as well :)

[ph0ph0]

This is incorrect still - when the lab is minted the event is indexed the BE seeds the shortname with a default, which is lab-<token-id>

[ph0ph0]

I'd remove this section

[ph0ph0]

Change to "Next"

[ph0ph0]

Put a sentence here stating that if the user is wants to upload an encrypted their file, to jump to the upload-encrypted-file tutorial with a link - otherwise they should proceed.

[ph0ph0]

We don't have an API Channel and this links to the General Chat Channel? I would maybe label this as General Channel so it doesn't confuse people and they go looking for the general channel