Codex/examples correctness pass

README.md

@@ -268,6 +268,24 @@ RPC source files now live under `docs/rpc/<category>/` and publish at `/rpc/<cat
 
 Use the generated `pageModelId` from `mike-docs`. The canonical hosted `/rpcs/...` and `/apis/...` routes are generated automatically; do not hand-edit files under `src/pages/rpcs/**` or `src/pages/apis/**`.
 
+### Examples Voice And Shape
+
+Examples pages are reference workflows for technical readers. A good example answers a real question a reader arrives with, and the RPC calls teach something about how NEAR actually works along the way. Keep them task-first and concise.
+
+- Start with the job and the first surface, not page philosophy.
+- Prefer exact endpoint or method names in the first sentence.
+- Use short imperative or declarative sentences.
+- Cut phrases like `plain-language`, `user story`, `the point here is`, and other author-to-author narration.
+- Avoid stacked framing. The heading plus one short lead line plus the `Flow` block is usually enough.
+- Keep pinned example metadata to the few facts the commands actually depend on.
+- Keep tables or Mermaid diagrams only when they reduce confusion. If the `Flow` block and commands already make the path obvious, cut them.
+- Do not add `Goal` or `Capture` sections unless they carry information the example does not already make obvious.
+- Every line before the first command should earn its place by doing one of three jobs: choose the surface, explain the signal to look for, or justify why the example is pinned.
+- Use examples to teach NEAR, not to verify the RPC. Pick a question a real reader would arrive with, not one contrived to exercise the RPC's correctness. "Which function-call keys might I want to remove" is real; "prove that `view_state` and `call_function` agree on the counter" is an RPC self-test — it adds surface without signal.
+- Give each subsection one question. If a single `###` is trying to answer several at once (cleanup *and* forensic attribution *and* a separate write flow), split it. Forensic trails — multi-hop joins, Delegate unwrapping, archival attribution — belong on their own pages, not as tails on lighter-weight sections.
+- Lead with the mental model when the RPC surface surprises a reasonable intuition. If the natural first guess (`block → tx`) doesn't match the actual path (`block → chunk → transactions`), say why up front. Otherwise readers spend the example wondering whether the author took a wrong turn.
+- Keep each example to one jq pipeline shaping one RPC response. When an example needs shell-variable joins across three RPCs to produce an answer, that's a signal it's really multiple examples.
+
 ## Canonical Route Contract
 
 These hosted paths remain the stable embed and reference contract:

docs/agents/auth-for-agents.mdx

@@ -12,7 +12,7 @@ page_actions:
 
 Agents should authenticate to FastNear the same way production backends do. Do not copy the browser-demo posture used by the docs UI into an agent, worker, or automation runtime.
 
-One FastNear API key works across the RPC and API endpoints. Many public reads still work without a key. For agents, the important question is not whether auth exists. It is where the credential lives, how it gets attached to requests, and how to avoid leaking it into prompts, logs, or browser state.
+One FastNear API key works across the RPC and API endpoints. For agents, the important question is not whether auth exists. It is where the credential lives, how it gets attached to requests, and how to avoid leaking it into prompts, logs, or browser state.
 
 ## If you only need the rule
 
@@ -36,8 +36,8 @@ Avoid browser-only agent architectures that need the FastNear key in client-side
 
 | Transport | Use it when... | Notes |
 | --- | --- | --- |
-| `Authorization: Bearer ${API_KEY}` | you control the HTTP client or backend | Best default for agents. Less likely to leak into URL logs, analytics, or copied links. |
-| `?apiKey=${API_KEY}` | you are using simple curl or a system that cannot easily set headers | Still valid, but URLs tend to travel further through logs and tooling. Use it intentionally. |
+| `Authorization: Bearer ${FASTNEAR_API_KEY}` | you control the HTTP client or backend | Best default for agents. Less likely to leak into URL logs, analytics, or copied links. |
+| `?apiKey=${FASTNEAR_API_KEY}` | you are using simple curl or a system that cannot easily set headers | Still valid, but URLs tend to travel further through logs and tooling. Use it intentionally. |
 
 If you have a choice, use the header form.
 
@@ -68,13 +68,13 @@ const response = await fetch('https://rpc.mainnet.fastnear.com', {
 });
 ```
 
-## When auth is missing
+## If the runtime is missing the key
 
-Many public FastNear endpoints are still readable without a key. If the agent can answer the user's question from public traffic, do that.
+Agents should normally start with a configured FastNear API key. Some public FastNear reads may still work without one, but that should not be the default operating posture.
 
-When a key is required for higher limits, paid access, or authenticated traffic:
+If the configured runtime does not have the key yet:
 
-- tell the user to create or retrieve a key from [dashboard.fastnear.com](https://dashboard.fastnear.com)
+- tell the user to create or retrieve a key from [FastNear Dashboard](https://dashboard.fastnear.com)
 - ask them to configure it in an env var, secret manager, or backend configuration
 - do not ask them to paste the raw key into chat so the agent can carry it around
 

docs/agents/index.mdx

@@ -25,6 +25,7 @@ This page is the operational starting point for AI agents, crawlers, and automat
 
 - Use indexed APIs when the user wants a product-shaped answer such as balances, holdings, account history, or transfer history.
 - Use [RPC Reference](/rpc) when the user needs canonical protocol-native fields, contract calls, or transaction submission.
+- If you are using the hosted JS runtime at [js.fastnear.com](https://js.fastnear.com), start with low-level methods such as `near.view`, `near.queryAccount`, and `near.tx.*`, and use `near.recipes.*` only when a task helper is the shortest path to the answer.
 - Use [NEAR Data API](/neardata) when the question is about recent optimistic or finalized blocks and explicit polling.
 - Use [Snapshots](/snapshots/) for operator workflows, not application-level data reads.
 - One FastNear API key works across the RPC and API endpoints.
@@ -98,20 +99,24 @@ Bad pattern:
 
 ## Authenticate once, reuse everywhere
 
-Public endpoints often work without a key. Add a key for higher limits, a shared authenticated posture, or paid access patterns. The same key works across every FastNear API above, including the regular and archival RPC hosts; send it either as an HTTP header or a URL parameter:
+Start with a FastNear API key and reuse it across every FastNear API above, including the regular and archival RPC hosts. Send it either as an HTTP header or a URL parameter:
 
 ```bash title="Authorization header"
+: "${FASTNEAR_API_KEY:?Set FASTNEAR_API_KEY in your shell before running this example.}"
+
 curl "https://rpc.mainnet.fastnear.com" \
-  -H "Authorization: Bearer ${API_KEY}" \
+  -H "Authorization: Bearer $FASTNEAR_API_KEY" \
   -H "Content-Type: application/json" \
   --data '{"method":"block","params":{"finality":"final"},"id":1,"jsonrpc":"2.0"}'
 ```
 
 ```bash title="URL parameter"
-curl "https://rpc.mainnet.fastnear.com?apiKey=${API_KEY}"
+: "${FASTNEAR_API_KEY:?Set FASTNEAR_API_KEY in your shell before running this example.}"
+
+curl "https://rpc.mainnet.fastnear.com?apiKey=$FASTNEAR_API_KEY"
 ```
 
-Get a key from [dashboard.fastnear.com](https://dashboard.fastnear.com). Operational posture for non-interactive runtimes: [Auth for Agents](/agents/auth) — keys go in env vars or a secret manager, never in browser storage, chat logs, or prompts. Full flow and header details: [Auth & Access](/auth).
+Get your API key from [FastNear Dashboard](https://dashboard.fastnear.com). Operational posture for non-interactive runtimes: [Auth for Agents](/agents/auth) — keys go in env vars or a secret manager, never in browser storage, chat logs, or prompts. Full flow and header details: [Auth & Access](/auth).
 
 ## Pull clean docs into a prompt
 

docs/api/examples.md

@@ -0,0 +1,206 @@
+---
+sidebar_label: Examples
+slug: /api/examples
+title: API Examples
+description: Task-first FastNear API examples for account lookup, holdings, and staking.
+displayed_sidebar: fastnearApiSidebar
+page_actions:
+  - markdown
+---
+
+## Examples
+
+All shell examples below work on the public FastNear API hosts as-is. If `FASTNEAR_API_KEY` is set in your shell, they add it as a bearer header automatically; if it is unset, they fall back to the public unauthenticated path.
+
+### Summarize one account in one call
+
+`/v1/account/{id}/full` is the FastNear API's account aggregator — one call bundles the account's NEAR state, every FT contract it's touched, every NFT collection it's received, and every validator pool it's delegated to. When you already have the `account_id`, this is the fastest "what does this account look like?" read.
+
+```bash
+ACCOUNT_ID=root.near
+AUTH_HEADER=()
+if [ -n "${FASTNEAR_API_KEY:-}" ]; then AUTH_HEADER=(-H "Authorization: Bearer $FASTNEAR_API_KEY"); fi
+
+curl -s "https://api.fastnear.com/v1/account/$ACCOUNT_ID/full" \
+  "${AUTH_HEADER[@]}" \
+  | jq '{
+      account_id,
+      near_balance_yocto: .state.balance,
+      ft_contracts: (.tokens | length),
+      nft_contracts: (.nfts | length),
+      staking_pool_contracts: (.pools | length)
+    }'
+```
+
+For `root.near`: 150 FT contracts in the list, 102 NFT collections, 2 staking pools. The contract counts alone tell you this is a busy mainnet account. Every example below drills into one of those surfaces — start here when all you have is the account ID.
+
+### Resolve a public key, then fetch the account snapshot
+
+Look up which account a key belongs to, then read that account's holdings in one call.
+
+```bash
+PUBLIC_KEY='ed25519:CCaThr3uokqnUs6Z5vVnaDcJdrfuTpYJHJWcAGubDjT'
+AUTH_HEADER=()
+if [ -n "${FASTNEAR_API_KEY:-}" ]; then AUTH_HEADER=(-H "Authorization: Bearer $FASTNEAR_API_KEY"); fi
+
+LOOKUP="$(curl -s "https://api.fastnear.com/v1/public_key/$(jq -rn --arg k "$PUBLIC_KEY" '$k | @uri')" \
+  "${AUTH_HEADER[@]}")"
+
+echo "$LOOKUP" | jq '{matched: (.account_ids | length), account_ids}'
+
+ACCOUNT_ID="$(echo "$LOOKUP" | jq -r '.account_ids[0]')"
+
+curl -s "https://api.fastnear.com/v1/account/$ACCOUNT_ID/full" \
+  "${AUTH_HEADER[@]}" \
+  | jq '{account_id, state, tokens: (.tokens|length), nfts: (.nfts|length), pools: (.pools|length)}'
+```
+
+If `matched` is greater than 1, switch to [V1 Public Key Lookup All](/api/v1/public-key-all) and loop over every returned account.
+
+### How much of this account's NEAR is actually spendable?
+
+NEAR account state has three buckets that wallet UIs tend to conflate: `balance` is the unstaked amount, `locked` is NEAR tied up in validator stake or a lockup contract, and `storage_bytes` implies a separate amount pinned to the trie at the current rate of 10^19 yoctoNEAR per byte. One pipeline over `/full` breaks them apart.
+
+```bash
+ACCOUNT_ID=root.near
+AUTH_HEADER=()
+if [ -n "${FASTNEAR_API_KEY:-}" ]; then AUTH_HEADER=(-H "Authorization: Bearer $FASTNEAR_API_KEY"); fi
+
+curl -s "https://api.fastnear.com/v1/account/$ACCOUNT_ID/full" \
+  "${AUTH_HEADER[@]}" \
+  | jq '
+      (.state.balance | tonumber) as $amount
+      | (.state.locked  | tonumber) as $locked
+      | (.state.storage_bytes * 10000000000000000000) as $pinned
+      | 1e24 as $ynear
+      | {
+          account_id,
+          near: {
+            total_owned:       (($amount + $locked) / $ynear),
+            unstaked:          ($amount / $ynear),
+            stake_or_lockup:   ($locked / $ynear),
+            pinned_to_storage: ($pinned / $ynear),
+            spendable:         (($amount - $pinned) / $ynear)
+          }
+        }'
+```
+
+For `root.near`: ~3914.67 NEAR total, all unstaked, ~0.28677 NEAR pinned to 28,677 bytes of on-chain state, and ~3914.38 NEAR spendable. New accounts feel this most acutely — a fresh named account of ~182 bytes has ~0.00182 NEAR stuck to storage, which is why CLI tools refuse to let you send an account's full balance.
+
+Point the same pipeline at a validator pool like `astro-stakers.poolv1.near` and the numbers invert: ~730 K unstaked, ~27.68 M in `locked`. That `locked` is the pool's own protocol-level validator stake, not the delegators' funds (those are tracked inside the pool contract's state). The same field means different things on different account types.
+
+jq uses IEEE-754 doubles, so the NEAR values above are display-precision only — keep the raw yocto strings if you need exact bookkeeping.
+
+### When did anything about this account last change?
+
+Every entry under `/full`'s `tokens`, `nfts`, and `pools` arrays carries its own `last_update_block_height` — the block at which the indexer last saw that row change for this account. Taking the max across all three arrays gives a cheap "latest activity" signal without touching the transaction API.
+
+```bash
+ACCOUNT_ID=root.near
+AUTH_HEADER=()
+if [ -n "${FASTNEAR_API_KEY:-}" ]; then AUTH_HEADER=(-H "Authorization: Bearer $FASTNEAR_API_KEY"); fi
+
+curl -s "https://api.fastnear.com/v1/account/$ACCOUNT_ID/full" \
+  "${AUTH_HEADER[@]}" \
+  | jq '
+      [
+        (.tokens // [])[].last_update_block_height,
+        (.nfts   // [])[].last_update_block_height,
+        (.pools  // [])[].last_update_block_height
+      ] as $heights
+      | ($heights | map(select(. != null))) as $tracked
+      | {
+          account_id,
+          total_entries:        ($heights | length),
+          tracked_entries:      ($tracked | length),
+          most_recent_block:    ($tracked | max),
+          oldest_tracked_block: ($tracked | min)
+        }'
+```
+
+For `root.near`, this returns 254 total entries across FT, NFT, and pool contracts, 158 with a tracked block, and a most-recent block of `194301659`. That's enough to tell you the wallet is still active without touching transaction history.
+
+This is the right question for "has this wallet been recently active?" or "has anything moved since block X?" — cheap, one call, no transaction history needed. For the transaction that caused the latest change, widen to the [Transactions API](/tx). Entries with `last_update_block_height: null` predate the indexer's per-row tracking (typically older airdrops) and are ignored here rather than counted as recent.
+
+### Show NFT collections this wallet holds from a specific publisher
+
+NEAR account names encode a hierarchy: `mint.sharddog.near` is a subaccount of `sharddog.near`, which is a subaccount of `near`. Publishers that ship multiple NFT collections usually deploy each one as its own subaccount, so a single suffix filter over the account's NFT list recovers everything under one publisher tree — no external collection registry required.
+
+```bash
+ACCOUNT_ID=root.near
+PUBLISHER=sharddog.near
+AUTH_HEADER=()
+if [ -n "${FASTNEAR_API_KEY:-}" ]; then AUTH_HEADER=(-H "Authorization: Bearer $FASTNEAR_API_KEY"); fi
+
+curl -s "https://api.fastnear.com/v1/account/$ACCOUNT_ID/nft" \
+  "${AUTH_HEADER[@]}" \
+  | jq --arg publisher "$PUBLISHER" '
+      ("." + $publisher) as $suffix
+      | {
+          account_id: .account_id,
+          publisher: $publisher,
+          collections: [
+            .tokens[]
+            | select(.contract_id | endswith($suffix))
+            | {
+                contract_id,
+                last_update_block_height,
+                status: (if .last_update_block_height == null then "dormant" else "active" end)
+              }
+          ] | sort_by(.last_update_block_height // 0)
+        }'
+```
+
+For `root.near` and `sharddog.near`, this returns four subaccount contracts: `ndcconstellationnft`, `mint`, `harvestmoon`, and `claim`. Only `claim` carries a non-null `last_update_block_height` (`131402024`), so that's the one contract where the wallet's position clearly changed. The others are dormant — common for drop-era contracts an account received into but never interacted with again.
+
+Swap `PUBLISHER` to any account to scope the filter to a different publisher tree.
+
+### Does this wallet show direct staking, liquid staking tokens, or both?
+
+Direct pool positions live on `/staking`; liquid staking tokens (stNEAR, LiNEAR, etc.) sit on `/ft` like any other FT. Read both, classify the wallet — `root.near` shows up as `mixed`.
+
+```bash
+ACCOUNT_ID=root.near
+LIQUID_PROVIDERS_JSON='["meta-pool.near","lst.rhealab.near","linear-protocol.near"]'
+AUTH_HEADER=()
+if [ -n "${FASTNEAR_API_KEY:-}" ]; then AUTH_HEADER=(-H "Authorization: Bearer $FASTNEAR_API_KEY"); fi
+
+STAKING="$(curl -s "https://api.fastnear.com/v1/account/$ACCOUNT_ID/staking" \
+  "${AUTH_HEADER[@]}")"
+FT="$(curl -s "https://api.fastnear.com/v1/account/$ACCOUNT_ID/ft" \
+  "${AUTH_HEADER[@]}")"
+
+jq -n \
+  --argjson staking "$STAKING" \
+  --argjson ft "$FT" \
+  --argjson providers "$LIQUID_PROVIDERS_JSON" '
+  ($staking.pools // []) as $direct
+  | (($ft.tokens // []) | map(select(.contract_id as $id | $providers | index($id)))) as $liquid
+  | {
+      classification: (
+        if ($direct|length)>0 and ($liquid|length)>0 then "mixed"
+        elif ($direct|length)>0 then "direct_only"
+        elif ($liquid|length)>0 then "liquid_only"
+        else "no_visible_staking_position" end
+      ),
+      direct_pools: ($direct | map(.pool_id)),
+      liquid_tokens: ($liquid | map({contract_id, balance}))
+    }'
+```
+
+The classifier only knows what you teach it — extend `LIQUID_PROVIDERS_JSON` as new liquid-staking products ship, and treat the result as observational rather than exhaustive.
+
+## Common mistakes
+
+- Leading with the broad account snapshot when the user only asked about one asset family.
+- Using FastNear API when the user explicitly needs exact RPC fields or permissions.
+- Staying in account-summary pages after the question turns into transaction history.
+
+## Related guides
+
+- [FastNear API](/api)
+- [API Reference](/api/reference)
+- [RPC Reference](/rpc)
+- [Transactions API](/tx)
+- [Choosing the Right Surface](/agents/choosing-surfaces)
+- [Agent Playbooks](/agents/playbooks)

docs/api/index.md

@@ -56,6 +56,10 @@ https://test.api.fastnear.com
 - [V1 public key](/api/v1/public-key) when you need account resolution from a key.
 - [V1 FT top holders](/api/v1/ft-top) for token-distribution views.
 
+## Need a workflow?
+
+Use [FastNear API Examples](/api/examples) for worked examples like account summaries, key-to-account resolution, and asset-specific follow-up.
+
 ## Troubleshooting
 
 ### I only need one low-level value from chain state