feat(docs): getting started for agents

.github/prompts/docs-sync.md

@@ -52,17 +52,23 @@ touches one of its source paths.
 | Docs page | Source paths in `desci-infra` |
 | -- | -- |
 | `api-reference/README.md` | `graphql/schemas/*.graphql` (surface inventory only), `lib/shared-api-stack.ts` |
-| `api-reference/authentication.md` | `lambda/appsync-authorizer-lambda/**`, service-token resolvers in `lambda/appsync-resolver-labs-lambda/**` (`services/token-manager-service.ts`), `docs/service-auth.md` |
+| `api-reference/authentication.md` | `lambda/appsync-authorizer-lambda/**`, service-token resolvers in `lambda/appsync-resolver-labs-lambda/**` (`services/token-manager-service.ts`, `utils/service-auth-message.ts`), `docs/service-auth.md`. The header reference and the sign-in flow both live here: a change to the sign-in message, its nonce or its validity window touches this page **and** `labs-api/service-tokens.md` **and** the tutorials' Step 1 — fix all of them or none. |
+| `api-reference/getting-started/README.md` | The onboarding entry point. `lib/desci-api-app-sync/constructs/api-config.ts` (endpoints, introspection, depth limit), `lambda/x402-gateway-lambda/**` (prices/base URLs quoted in the cost table), `lambda/appsync-authorizer-lambda/**` (credential shape). **Contains live deployment values** — `mintFeeWei()` behaviour, x402 prices, gateway URLs, contract addresses. Never update one of those from a diff alone: if the diff suggests a value changed, flag it in the PR body and let a human re-verify against the deployed environment. |
+| `api-reference/getting-started/shared-setup.md` | The config constants and helpers every tutorial's snippets assume: staging endpoint, chain, `FACTORY_ADDRESS` / `LABNFT_ADDRESS` / `ACCESS_RESOLVER_ADDRESS`, plus `graphql()`, `parseDetails()`, `assertOk()` and `withIndexerLagRetry()`. Sources: `lib/desci-api-app-sync/constructs/api-config.ts` (endpoints), `graphql/schemas/api-error.graphql` and the in-band `ApiError` shape (`parseDetails`/`assertOk`), `lambda/appsync-authorizer-lambda/**` (header names). Contract addresses are deployment values — flag a suspected change for human verification rather than editing from a diff. **This block is duplicated inline in each tutorial's complete script and in the production swap table on `getting-started/README.md`: fix all copies or none.** |
+| `api-reference/getting-started/for-agents.md` | Condensed mirror of Create a lab and upload a public file plus the error contract. Sources: `graphql/schemas/ip-hubs.graphql`, `graphql/schemas/api-error.graphql`, `graphql/schemas/encryption.graphql`, `lambda/appsync-resolver-labs-lambda/**` (per-mutation role gates). **Must stay consistent with the tutorial pages** — a change to the flow touches this page and the relevant tutorial, or neither. |
+| `api-reference/getting-started/create-lab-and-upload-file.md` | Create a lab and upload a public file — self-issue a token, mint, `createLab`, three-call public upload, verify. Sources: `graphql/schemas/ip-hubs.graphql`; `lambda/appsync-resolver-labs-lambda/**` for `generateServiceToken`, `createLab`, `initiateCreateOrUpdateFile`, `finishCreateOrUpdateFile` and their authorization gates; `services/token-manager-service.ts`; `lib/utils/token-expiration.ts` (the `expiresIn` default and bounds). Every code block is expected to be runnable — a signature change here is a real breakage, so correct it and say so in the PR body. Steps 1–3 are duplicated by reference in Upload an encrypted file and Agent access: **fix all copies or none.** |
+| `api-reference/getting-started/upload-encrypted-file.md` | Upload an encrypted file — DEK, local AES-256-GCM, `accessControlConditions`, `encryptionMetadata`, `decryptDataKey` round trip. Sources: `graphql/schemas/encryption.graphql`, `lambda/common/services/kms-service.ts`, the encryption resolvers and condition evaluator in `lambda/appsync-resolver-labs-lambda/**`, `lib/encryption-stack.ts`. `encryptionSystem` is backend-set and must stay "echo it verbatim" — never let a literal be hardcoded here. |
+| `api-reference/getting-started/agent-as-a-lab-contributor.md` | Agent access — a Contributor-role agent writing into a lab a human owns. Sources: the per-mutation service-token gates in `lambda/appsync-resolver-labs-lambda/**` (`authorizeServiceMember` = Contributor, `authorizeServiceAdmin` = Owner) and `services/auth-service.ts`. **If a content-write mutation moves between those two gates, this page's role claims and its Owner-only list are wrong** — that is the single highest-value thing to check here. Role grants themselves are onchain (`AccessResolver`), out of this repo. |
+| `references/glossary.md` | Plain-language definitions of every Molecule term used in the API docs (Lab, LabNFT, `oclId`, data room, Kamu, roles, service token, consumer credential, x402, indexer). Definitions are summarised from `technical-deep-dive/**` and the Labs API pages rather than from source directly — if a diff changes what one of those terms *means* (a renamed identifier, a changed role name, a new credential type), update the entry here as well as the page it came from. Never let this page and the deep-dive pages disagree. |
 | `api-reference/labs-api/README.md` | `graphql/schemas/ip-hubs.graphql`, `lambda/appsync-resolver-labs-lambda/**` |
 | `api-reference/labs-api/lab-management.md` | `createLab`, `updateLabNftMetadata`, `generateLabImageUploadUrl` in `lambda/appsync-resolver-labs-lambda/**`; `lambda/labnft-metadata-lambda/**`; `lambda/ocl-processor/**` |
 | `api-reference/labs-api/files.md` | file operations in `lambda/appsync-resolver-labs-lambda/**` (`initiateCreateOrUpdateFile`, `finishCreateOrUpdateFile`, `deleteDataRoomFile`, `updateFileMetadata`, `moveEntry`), `graphql/schemas/encryption.graphql`, `lambda/common/services/kms-service.ts` |
 | `api-reference/labs-api/browse-and-search.md` | `labs`, `searchLabs`, `labWithDataRoomAndFiles`, `dataRoomFile`, `activities`, `labActivity` resolvers; `graphql/schemas/onchain-activity.graphql` |
-| `api-reference/labs-api/legal-agreements.md` | `signLegalAgreement`, `legalAgreementTemplate`, `legalAgreementStatus` resolvers |
-| `api-reference/labs-api/service-tokens.md` | `generateServiceToken`, `extendServiceToken`, `revokeServiceToken` resolvers in `lambda/appsync-resolver-labs-lambda/**` (`services/token-manager-service.ts`); `lambda/appsync-authorizer-lambda/**` |
+| `api-reference/labs-api/legal-agreements.md` | `signLegalAgreement`, `legalAgreementTemplate`, `legalAgreementStatus` resolvers — **frozen and hidden** (`hidden: true`, out of `SUMMARY.md`) since IP-3028: the assignment agreement is no longer a gate on anything and the feature may be removed. Correct outright errors only; never expand it, and never re-introduce a `legalAgreement*` mention into `getting-started/**`, `authentication.md`, `labs-api/README.md` |
+| `api-reference/labs-api/service-tokens.md` | `generateServiceToken`, `extendServiceToken`, `revokeServiceToken` resolvers in `lambda/appsync-resolver-labs-lambda/**` (`services/token-manager-service.ts`); `utils/service-auth-message.ts` and the sign-in nonce constants (`SIGNIN_NONCE_VALIDITY_MS` — the documented 10-minute window) in `services/token-manager-service.ts`; `lambda/appsync-authorizer-lambda/**`. **The documented `details.reason` values (`NONCE_NOT_FOUND`, `NONCE_EXPIRED`, `INVALID_SIGNATURE`) are the complete set the `generateServiceToken` signature path emits** — `WALLET_MISMATCH` is *not* one of them (it belongs to the legal-agreement resolvers' Privy path), and `expiresIn` is not validated in this resolver, so a bad value surfaces as `INTERNAL_ERROR` / `TOKEN_GENERATION_FAILED` — keep the table and the validity window in step with it |
 | `api-reference/tokenization-api.md` | `graphql/schemas/evm-tokenization.graphql`, `lambda/appsync-resolver-evm-tokenization/**`, `lib/evm-tokenization-service-stack.ts` |
 | `api-reference/x402-gateway.md` | `lambda/x402-gateway-lambda/**` |
-| `api-reference/ipnft-api-deprecated.md` | `lambda/desci-api-lambda/**` (legacy IPNFT resolvers), `lambda/desci-ipnfts-processor/**`, `lambda/ipnft-events-lambda/**` — **deprecated: correct errors, never expand** |
-| `api-reference/changelog.md` | `graphql/schemas/**`, `prisma/schema.prisma` — breaking changes and migrations only |
+| `api-reference/changelog.md` | `graphql/schemas/**`, `prisma/schema.prisma` — breaking changes and migrations only. **The "Typical `details.reason`" column lists only values the backend actually emits today**, verified against `lambda/common/errors/legacy-mapping.ts` (`LEGACY_CODE_MAP`) and the `details: { reason: … }` literals in `lambda/**`. Do **not** copy aspirational reasons out of desci-infra's `docs/api-standards.md` or `docs/error-codes.md` — those spec pages list planned values (`FILTER_COMPLEXITY_LIMIT`, `RESULT_CARDINALITY_LIMIT`, `TOKEN_EXPIRED`, `NOT_CONTRIBUTOR`, `SERVICE_NOT_WHITELISTED`) that no code path emits. A reason belongs in this table only if you can point at the line that returns it |
 | `release-notes/*.md` | any consumer-visible change (see the release-notes step) |
 | `technical-deep-dive/data/data-api-and-integration.md` | `lambda/kamu-client-lambda/**`, `lambda/did-linking-worker/**` |
 | `technical-deep-dive/data/data-privacy-and-access.md` | `graphql/schemas/encryption.graphql`, `lambda/common/services/kms-service.ts`, encryption resolvers in `lambda/appsync-resolver-labs-lambda/**`, `lib/encryption-stack.ts` |
@@ -73,7 +79,6 @@ touches one of its source paths.
 
 > **Triggering vs ride-along paths.** The relevance gate in
 > `.github/workflows/docs-sync.md` starts a run for a *subset* of the paths above. The deprecated
-> IPNFT lambdas (`desci-api-lambda`, `desci-ipnfts-processor`, `ipnft-events-lambda`)
 > and `lib/*.ts` files beyond `shared-api-stack` / `evm-tokenization-service-stack` /
 > `encryption-stack` never start a run on their own — their pages update only when a triggering
 > path changed in the same release. That is deliberate; keep the gate small.
@@ -84,9 +89,7 @@ touches one of its source paths.
 `introduction/**`, `user-guides/**`, `legal-framework/**`, `security/**` (narrative and legal pages,
 not driven by a backend diff), `technical-deep-dive/onchain-lab.md` and
 `technical-deep-dive/module-registry/**` (source: the `onchainlabs` / `ocltokenizer` contracts),
-`technical-deep-dive/data/README.md` (section landing page, narrative only), and
-`api-reference/IPNFT-api.md` — an orphan duplicate of `ipnft-api-deprecated.md` that is not in
-`SUMMARY.md`; never edit it, and a human should decide whether to delete it.
+and `technical-deep-dive/data/README.md` (section landing page, narrative only).
 
 ## What is not source of truth
 
@@ -140,8 +143,6 @@ These exist because of the July 2026 docs audit. They are not optional.
    — do not create it. The one exception is a new file under `release-notes/`, which is expected.
 5. **Do not restate internal work.** Refactors, test changes, dependency bumps, infrastructure and
    CI changes are invisible to consumers and must not reach a page.
-6. **Deprecated surfaces are frozen.** On `api-reference/ipnft-api-deprecated.md`, correct outright
-   errors only. Never document new capability there.
 7. **Scope discipline.** Only edit pages the map connects to paths in this diff. A tempting unrelated
    improvement belongs in the PR body as a suggestion, not in the diff.