Documentation and UI

docs/marketplace.md

@@ -1,4 +1,16 @@
-# Marketplace sandbox
+# Peer-hosted markets
+
+Every Wikideck peer can host its own market for cards on the shared NFT blockchain. A host can serve collectors broadly or build a community around a particular collection, theme or subject. Card ownership and confirmed transfers follow the shared chain; each host keeps its own listings, bids and order journal. Buyers and sellers must use the same host to complete a sale.
+
+The current market provides fixed-price sales and timed auctions. Running a collection-focused community is possible today, but built-in collection-specific admission, moderation and curation controls are not implemented. Peer-hosted custom trading card games are also planned, not available yet. Operators can adapt the source and presentation subject to licensing; the project still needs a published software license before open-source reuse rights can be claimed. See [project direction and licensing](../README.md#peer-ownership-and-customization).
+
+## Cryptocurrency payments and the two sale fees
+
+The intended settlement currency is **Monero (XMR)**, with USD-priced listings and an XMR amount quoted at checkout. Mining and payments are separate: RandomX secures Wikideck's own blockchain, while XMR payments would settle on Monero.
+
+Each sale allocates a configurable hosting fee to the peer's market operator (default **2.5%**) plus a hardcoded **1% author fee** to the project author's fixed XMR address. Both are deducted from the seller's gross proceeds, not compounded or secretly added to the buyer price. At the default rates the seller keeps 96.5% before any future disclosed processor/network-fee policy. The host retains the hosting allocation; the author allocation is a separate payout. **All allocations and payouts are currently simulated.**
+
+## Current testnet sandbox
 
 Open **Marketplace** in the interface. Prices are **USD**; checkout amounts, fees, refunds, and automatic seller payouts are simulated in **XMR**. There is no payable address, payment processor connection, or movement of real Monero in this release. The displayed exchange rate is a deterministic simulation fixture, not a market quote. **Signing delivery transfers the actual card on the selected chain**, even though payment is mocked.
 
@@ -37,9 +49,9 @@ The single-node and three-node testnet Compose configurations pass these setting
 
 Money is stored as integer USD cents and calculated in integer Monero atomic units (12 decimal places). Gross XMR is rounded up to an atomic unit; each fee is rounded down separately; seller net is exactly gross minus both fees. Maximum listing/bid price is $1,000,000.00.
 
-## Fixed additional 1% fee
+## Hardcoded 1% project author fee
 
-Every new marketplace sale (fixed price or winning auction) includes a **hardcoded additional 1% seller fee**, on top of the configurable hosting fee. Both fees are calculated independently on the gross sale proceeds, not compounded. At the default 2.5% hosting fee the combined deduction is **3.5%**. Setting the hosting fee to zero does **not** disable the additional 1%.
+Every new marketplace sale (fixed price or winning auction) includes a **hardcoded 1% project author fee**, on top of the configurable fee for the hosting peer's operator. Both fees are calculated independently on gross sale proceeds, not compounded. At the default 2.5% hosting fee the combined deduction is **3.5%**. Setting the hosting fee to zero does **not** disable the author fee.
 
 The fixed public XMR payout recipient is:
 

docs/randomx-native.md

@@ -1,8 +1,8 @@
 # Native RandomX engine
 
-This is the CPU proof engine used by the Wikideck testnet node and explicit opt-in
-native miner. Mining runs only when the operator starts the native CLI; the browser
-does not mine or launch native programs. The Docker image builds this pinned
+Wikideck's native CPU proof engine uses RandomX, the algorithm also used by Monero,
+designed to keep general-purpose consumer CPUs competitive. Mining a Wikideck block
+rewards its miner with a Wikipedia NFT card on Wikideck's independent chain. The Docker image builds this pinned
 implementation and runs its known-vector test. There is no GPU path, simulated hash,
 or production fallback hash.