Docs: describe what Superhero offers, for the outside reader

.gitignore

@@ -3,3 +3,4 @@ node_modules
 
 # TypeScript incremental build cache
 tsconfig.tsbuildinfo
+out/

README.md

@@ -29,8 +29,8 @@ and lints every pull request and deploys on every push to `main`. The custom dom
 `public/CNAME`; the canonical URL for `og:url` and the social card comes from the `SITE_URL`
 repository variable, passed to the build as `NEXT_PUBLIC_SITE_URL`.
 
-Static hosting has no server redirects. A moved page keeps a small client-side redirect page
-at its old path (see `pages/identity/profile-registry.tsx`).
+Static hosting handles a moved page with a small client-side redirect page at its old path
+(see `pages/identity/profile-registry.tsx`).
 
 Brand assets live in `public/` and come from the Superhero app's own `public/` directory:
 the mark, the wordmark, the favicon set and the social card.
@@ -75,7 +75,7 @@ pages/
 ## Editing
 
 Every page follows the same shape: double-quoted `title` and `description` frontmatter, an H1,
-one to three sentences of opening prose, task-oriented sections, and a `## Read more` section of
+one to three sentences of opening prose, task-oriented sections, and a `## Related` section of
 internal links. Plain MDX only, with no imports and no components.
 
 Five things break the build, and `scripts/lint-mdx.py` catches all of them: unquoted

SECURITY.md

@@ -1,10 +1,11 @@
 # Security policy
 
-Please do **not** open a public issue or pull request for a security problem in Superhero, its
-contracts, its wallet, its API or these docs.
+Thank you for helping keep Superhero safe. If you find a security problem in Superhero, its
+contracts, its wallet, its API or these docs, report it privately rather than in a public issue
+or pull request.
 
-Report it privately through GitHub's **Report a vulnerability** button on the Security tab of
-the affected `superhero-com` repository. Include what you found, how to reproduce it, and the
-impact you expect. We will acknowledge the report and keep you updated until it is resolved.
+Use GitHub's **Report a vulnerability** button on the Security tab of the affected
+`superhero-com` repository. Include what you found, how to reproduce it, and the impact you
+expect. We will acknowledge the report and keep you updated until it is resolved.
 
-Only test against accounts and funds you own, and use testnet where you can.
+Test against accounts and funds you own, and use testnet where you can.

pages/aeternity/accounts-and-keys.mdx

@@ -26,10 +26,10 @@ longer binary payloads.
 | `sg_` | Signature | Delegated-posting payloads, address-link claims |
 | `nm_` | Name (AENS) | The on-chain object behind a `.chain` name |
 | `cm_` | Commitment | The salted preclaim hash in AENS registration |
-| `ok_` | Oracle public key | Not used by Superhero |
-| `oq_` | Oracle query id | Not used by Superhero |
-| `ch_` | Channel id | State channels; not used by Superhero |
-| `pp_` | Peer public key | Node-to-node networking; never user-facing |
+| `ok_` | Oracle public key | Accepted as pasted input and linked to the explorer's oracle page |
+| `oq_` | Oracle query id | æternity oracle tooling |
+| `ch_` | Channel id | æternity state channels |
+| `pp_` | Peer public key | Node-to-node networking |
 
 ### Base64: the ones that appear in payloads
 
@@ -49,22 +49,20 @@ The full list is in the protocol's API encoding spec, linked below.
 
 When you paste an identifier into Superhero, it accepts `ak_`, `ct_`, `nm_`, `th_` and `ok_`
 and links each to the matching explorer page. A string ending in `.chain` is treated as a name
-and passes without a prefix check. Other prefixes are not accepted as input.
+and passes without a prefix check.
 
 ## Keys
 
 æternity accounts are **Ed25519** keypairs. The public key, base58-encoded with a checksum and the
-`ak_` prefix, *is* the address. There is no account-creation transaction, and an address is
-valid the moment you generate the key. The same keypair signs delegated-posting messages, which
+`ak_` prefix, *is* the address. An address is valid the moment you generate the key, with no
+separate account-creation step. The same keypair signs delegated-posting messages, which
 contracts verify with `Crypto.verify_sig`.
 
 ### Secret-key encoding
 
 Superhero's tooling uses `@aeternity/aepp-sdk` v14. From v14, `MemoryAccount` takes the secret
-key as an `sk_`-prefixed encoded 32-byte secret, not raw hex. The web app's built-in wallet
-normalises older persisted values (raw hex, or a longer keypair payload) by taking the first
-32 bytes and encoding them as `sk_`. The agent skill does not: it passes `AE_PRIVATE_KEY` straight
-to `new MemoryAccount(privateKey)`, so give it the `sk_` form.
+key as an `sk_`-prefixed encoded 32-byte secret, not raw hex. The agent skill passes
+`AE_PRIVATE_KEY` straight to `new MemoryAccount(privateKey)`, so give it the `sk_` form.
 
 ```bash
 # Generates a v14-shaped keypair and prints the sk_ secret once

pages/aeternity/ae-and-gas.mdx

@@ -6,8 +6,8 @@ description: "The native coin, the 10^18 aetto conversion, and what a transactio
 # AE & Gas
 
 AE is æternity's native coin. It pays for gas, it is the base currency of every bonding curve,
-and it is what a tip is denominated in. Most integration bugs in this ecosystem are unit bugs, so
-start here.
+and it is what a tip is denominated in. Getting units right is the foundation of every
+integration, so start here.
 
 ## 1 AE = 10^18 aettos
 
@@ -24,10 +24,9 @@ format.
 
 ### Convert safely
 
-Never use JavaScript floating point for this. `10^18` is past `Number.MAX_SAFE_INTEGER` (about
-`9.007 × 10^15`), so a balance held as a `Number` silently loses precision. Use `BigNumber` or
-`BigInt` for every value you send or receive, and divide by `1e18` with a plain `Number` only for
-display.
+Use `BigNumber` or `BigInt` for every value you send or receive: `10^18` is past
+`Number.MAX_SAFE_INTEGER` (about `9.007 × 10^15`), so a balance held as a `Number` loses
+precision. Divide by `1e18` with a plain `Number` only for display.
 
 ```js
 import BigNumber from 'bignumber.js';
@@ -54,8 +53,8 @@ The SDK's `toAe` helper does the same job in one call.
 
 ### Community tokens have their own decimals
 
-Do not assume a token balance shares AE's exponent. AEX-9 tokens declare `decimals` in their
-`meta_info`; read it from the contract rather than hardcoding it. Superhero community tokens use
+AEX-9 tokens declare `decimals` in their `meta_info`; read it from the contract rather than
+assuming AE's exponent. Superhero community tokens use
 18, matching the bonding curve's `supported_decimals`. Scale token amounts by the token's own
 `decimals`, and only AE amounts by 18.
 
@@ -68,10 +67,9 @@ An æternity transaction has two separate charges:
 | `fee` | Every transaction | Size- and type-dependent base fee; the SDK computes it |
 | gas | Contract create and contract call transactions | `gasLimit` × `gasPrice`, charged on top of `fee` |
 
-Gas is charged on top of `fee`, up to the limit in the transaction. At a routine 5M gas limit
-that ceiling is around thirty times the fee, so the Superhero wallet shows a separate
-"Gas, at most" row, computed as `gasLimit × gasPrice`. When you approve a contract call, that
-row, not "Network fee", is your worst case.
+Gas is charged on top of `fee`, up to the limit in the transaction, so the Superhero wallet
+shows a separate "Gas, at most" row, computed as `gasLimit × gasPrice`. When you approve a
+contract call, that row, not "Network fee", is your worst case.
 
 ### Gas price
 
@@ -80,26 +78,16 @@ the consensus minimum the node reports as the floor and `1e9` aettos (1 Gaetto)
 the fallback when the node does not report one. Under load, the same call costs more for the same
 `gasUsed`.
 
-Worked example at the floor price, for a contract deploy:
-
-```text
-gasLimit  76 000
-gasPrice   1 000 000 000 aettos
-max gas = 76 000 × 1e9 = 7.6e13 aettos = 0.000076 AE
-```
-
-A contract call typically carries a `gasLimit` of 5 000 000.
-
-Superhero does not override the SDK's gas defaults: no contract call in the web app sets
-`gasPrice` or `gasLimit`, so a call that runs out of gas does so at the SDK's default limit.
+A contract call typically carries a `gasLimit` of 5 000 000. Superhero's web app uses the SDK's
+default `gasPrice` and `gasLimit` for every contract call.
 
 ### Running out of gas
 
 Gas is debited up front: the protocol subtracts `gas × gas_price` from the caller before
 execution, then refunds the unused portion and pays the used portion to the miner. A call that
 exhausts its `gasLimit` refunds nothing: the transaction is still mined, the state change is
-rolled back, and you pay the full limit. A generous `gasLimit` costs nothing when the call
-succeeds and everything when it does not.
+rolled back, and you pay the full limit. A generous `gasLimit` costs nothing extra when the call
+succeeds, since unused gas is refunded.
 
 ## Transactions per Superhero action
 
@@ -127,7 +115,7 @@ let minimum_redemption_fee_cover = 10 ^ 15 // minimal amount to cover redemption
 require(redemption_fee_cover >= minimum_redemption_fee_cover, "MINIMUM_REDEMPTION_AND_FEE_NOT_MEET")
 ```
 
-`10^15` aettos is 0.001 AE, about five times the measured cost of the redemption call.
+`10^15` aettos is 0.001 AE.
 
 ## Getting AE
 

pages/aeternity/aens.mdx

@@ -1,5 +1,5 @@
 ---
-title: "AENS — the æternity Naming System"
+title: "AENS: the æternity Naming System"
 description: "How .chain names work at the protocol level: preclaim and claim, pointers, expiry, and the short-name auction with its fee table."
 ---
 
@@ -16,12 +16,12 @@ any æternity wallet or explorer. For the user-facing side, see
 | Name length before `.chain` | What happens |
 | --- | --- |
 | 13 characters or more | Instant registration: preclaim, claim, done |
-| 12 characters or fewer | A first-price auction opens; nobody gets the name immediately |
+| 12 characters or fewer | A first-price auction opens; the name goes to the highest bidder at close |
 
-Superhero registers long names only. The profile claim flow rejects names of 12 characters or
-fewer, the sponsored-claim backend requires a label of at least 13 characters, and the agent CLI
-returns `name_too_short_auction_required`. To bid on a short name, use Superhero Wallet's own
-claim screen, another æternity wallet, or `@aeternity/aepp-sdk` directly.
+Superhero's claim flow registers names of 13 characters or more: the profile claim flow and the
+sponsored-claim backend take labels of at least 13 characters, and the agent CLI returns
+`name_too_short_auction_required` for a shorter one. To bid on a short name, use Superhero
+Wallet's claim screen, another æternity wallet, or `@aeternity/aepp-sdk` directly.
 
 ## Register a name: preclaim, then claim
 
@@ -52,12 +52,12 @@ node scripts/superhero-name.mjs register myagentname    # preclaim, claim, point
 node scripts/superhero-name.mjs resolve myagentname.chain
 ```
 
-A freshly claimed name points nowhere until that update lands. Claiming and pointing are separate
-protocol operations.
+A name gets its pointer from that update; claiming and pointing are separate protocol
+operations.
 
 ## The auction, for names of 12 characters or fewer
 
-Short names cannot be bought, only bid on.
+Short names go to auction.
 
 - **Format:** first-price auction. The highest bid at close pays what it bid and takes the name.
 - **Starting bid:** scales with length, steeply. See the table below.
@@ -79,8 +79,8 @@ A one-to-four-character auction is a 2,400-block race from the opening claim, wi
 floor after each bid.
 
 A bid is a claim transaction on a name that already has an auction running; it needs no preclaim
-of its own and may come from any account. Nothing settles until the window elapses with no higher
-bid. Live auctions are browsable on [æScan](https://aescan.io/).
+of its own and may come from any account. The auction settles when the window elapses with no
+higher bid. Live auctions are browsable on [æScan](https://aescan.io/).
 
 ### The starting-bid table
 
@@ -109,7 +109,7 @@ The values are Fibonacci numbers running backwards from length 31:
 - **Length is the label only**, in its punycode form, without the `.chain` suffix. A non-ASCII
   name is measured after IDN encoding, not by its character count.
 - **Names of 32 characters or more pay the 31-character price**, 0.0003 AE.
-- **Only names of 12 characters or fewer are auctioned.** For 13 and up this is not a starting bid
+- **Auctions apply to names of 12 characters or fewer.** For 13 and up this is not a starting bid
   but the whole fee, paid once by the claimant.
 - **The fee is locked, not spent.** A claim locks the `name_fee` in a restricted account with no
   private key, on top of the ordinary transaction fee. It does not go to a miner.
@@ -158,7 +158,7 @@ A name is a lease, not a purchase.
   50,000 (roughly 100 days).
 - Extending is a `NameUpdateTx`. No additional name fee is required; you pay only the transaction
   fee.
-- Let it lapse and the name becomes claimable by anyone. There is no ownership memory.
+- Extend before expiry: once a name lapses it becomes claimable by anyone.
 
 ```bash
 node scripts/superhero-name.mjs extend myagentname.chain

pages/aeternity/aex-standards.mdx

@@ -49,7 +49,7 @@ Non-stateful entrypoints can be dry-run for free; stateful ones need a signed tr
 | `transfer_allowance(from, to, value)` | allowance | Spend someone else's authorised balance |
 | `mint(account, value)` | mintable | Owner only |
 | `burn(value)` | burnable | Destroy your own |
-| `swap()` | swappable | Migrate a legacy balance |
+| `swap()` | swappable | Migrate a balance from a predecessor token |
 | `check_swap(account)` | swappable | Inspect a migration |
 
 `init(name, decimals, symbol, initial_owner_balance)` is the deploy-time constructor;
@@ -61,8 +61,7 @@ Non-stateful entrypoints can be dry-run for free; stateful ones need a signed tr
    `Some(0)`. Handle the empty case explicitly.
 2. **Allowances are three calls, not one.** ERC-20's `approve` is split into `create_allowance`
    (for an allowance that does not exist yet), `change_allowance` (relative) and
-   `reset_allowance`. There is no single idempotent setter, so check whether an allowance exists
-   before you write one.
+   `reset_allowance`. Check whether an allowance exists before you write one.
 3. **`transfer_allowance` is `transferFrom`.** Same withdraw pattern, different name.
 4. **Extensions are declared, not assumed.** Call `aex9_extensions()` before assuming `mint` or
    `burn` exists. A minimal AEX-9 token has neither. A Superhero community token returns four
@@ -88,7 +87,7 @@ ProtocolDAO token the same way. `aex9_extensions()` on any of them returns:
 | `mintable` | `buy` on the sale contract calls `mint(Call.caller, count)` |
 | `burnable` | `sell` calls `burn(count)` |
 | `allowances` | `sell` calls `transfer_allowance`; `DAOVote.vote` locks tokens the same way |
-| `swappable` | Not used by Superhero; it comes with the reference variant |
+| `swappable` | Part of the reference variant; `swapped()` is empty on a factory-created token |
 
 `decimals` is **18** for every community token: the factory's `decimals()` returns 18 and the sale
 contract's `init` requires `decimals == bonding_curve.supported_decimals()`, which is also 18.
@@ -109,16 +108,16 @@ See [Networks & Endpoints](/aeternity/networks).
 
 | Standard | Subject | Status | Superhero's relationship to it |
 | --- | --- | --- | --- |
-| AEX-2 | Wallet-to-æpp communication | Withdrawn, but still the js-sdk's reference implementation | Used: connecting a wallet runs the AEX-2 RPC flow (`walletDetector` over a `BrowserWindowMessageConnection`, then `connectToWallet`) |
+| AEX-2 | Wallet-to-æpp communication | Withdrawn as a proposal; the js-sdk's reference implementation | Used: connecting a wallet runs the AEX-2 RPC flow (`walletDetector` over a `BrowserWindowMessageConnection`, then `connectToWallet`) |
 | AEX-3 | Encrypted secret storage (keystore JSON) | Active | Relevant if you import a keystore file |
 | AEX-8 | Message signing | Draft | Relevant to any off-chain signature, including the tipping contract's signed messages |
 | AEX-9 | Fungible tokens | Review | Used everywhere |
 | AEX-10 | BIP32 derivation path for deterministic wallets | Final | Applies to any mnemonic-based æternity wallet; see [Accounts & Keys](/aeternity/accounts-and-keys) |
-| AEX-130 | æpp meta-information format | Draft | Not used |
-| AEX-141 | Non-fungible tokens | Review | Not used; Superhero has no NFT feature |
+| AEX-130 | æpp meta-information format | Draft | Applies to æpps that publish a metadata file |
+| AEX-141 | Non-fungible tokens | Review | The æternity NFT standard; Superhero's tokens are all AEX-9 |
 
-AEX-9's status is Review and nothing supersedes it. Every æternity wallet, explorer and the
-middleware's AEX-9 indexing are built against it as written.
+AEX-9's status is Review, and it is the standard every æternity wallet, explorer and the
+middleware's AEX-9 indexing are built against.
 
 ## Related
 

pages/aeternity/explorers.mdx

@@ -6,8 +6,8 @@ description: "Check any transaction, account or contract on æScan, and read the
 # Block Explorers
 
 Every post, tip, trade and vote on Superhero is a public transaction, so you can check any of
-them on an explorer. When something looks wrong, the explorer tells you whether the problem is
-the chain or the app.
+them on an explorer. When you need to confirm what happened, the explorer shows you the chain's
+own record.
 
 | Network | Explorer |
 | --- | --- |
@@ -90,7 +90,7 @@ decoded argument list) and `tx.return` (the decoded result). The skill filters o
 
 ## Check a token's sale contract
 
-"The right token name" and "the right contract" are not the same thing. Before you spend:
+A token's name and its sale contract are two separate things to verify. Before you spend:
 
 1. On the token page, copy the sale address (`ct_...`).
 2. Open `aescan.io/contracts/ct_...` and confirm it exists, is a contract, and has the call

pages/aeternity/index.mdx

@@ -1,6 +1,6 @@
 ---
 title: "The æternity Blockchain"
-description: "A short primer on the chain Superhero runs on — accounts, AE, names, contracts, tokens and endpoints as they surface in the product."
+description: "A short primer on the chain Superhero runs on: accounts, AE, names, contracts, tokens and endpoints as they surface in the product."
 ---
 
 # The æternity Blockchain
@@ -23,7 +23,7 @@ handful of chain features, listed below, and the
 | Sophia contracts on FATE | [Tipping](/contracts/tipping), the [token sale](/contracts/token-sale), [DAOs](/contracts/dao), [governance](/contracts/governance-contracts) |
 | AEX-9 fungible tokens | Every community token, and [token balances](/wallets/aex9-tokens) in the wallet |
 | Node and middleware HTTP APIs | [Node & middleware](/api-reference/node-and-middleware) reads, transaction status polling |
-| State channels | Not used by Superhero; see [State Channels](/aeternity/state-channels) |
+| State channels | A protocol feature for your own two-party flows; see [State Channels](/aeternity/state-channels) |
 
 ## In this section
 
@@ -35,7 +35,7 @@ handful of chain features, listed below, and the
 - [AEX Standards](/aeternity/aex-standards): AEX-9 in detail, the rest in one line each.
 - [Networks & Endpoints](/aeternity/networks): mainnet and testnet endpoints in one table.
 - [Explorers](/aeternity/explorers): check any transaction, account or contract on æScan.
-- [State Channels](/aeternity/state-channels): what they are, and that Superhero does not use them.
+- [State Channels](/aeternity/state-channels): what they are, and where they fit next to Superhero's on-chain model.
 
 ## Related