docs: move package docs to per-package READMEs

README.md

@@ -5,7 +5,7 @@
 
 <p align="center">
   <a href="docs/overview.md">Overview</a> &bull;
-  <a href="docs/packages/">Packages</a> &bull;
+  <a href="#packages">Packages</a> &bull;
   <a href="docs/flows/">Flows</a> &bull;
   <a href="docs/diagrams/">Diagrams</a> &bull;
   <a href="docs/glossary.md">Glossary</a> &bull;
@@ -24,8 +24,8 @@ Consumers pick metadata only, or the full trading toolkit on top of it.
 
 | Package | Role | Status |
 |---|---|---|
-| [`@quickswap-defi/protocol-core`](docs/packages/protocol-core.md) | Chain configs, protocol versions, fees, native + stablecoin metadata | Published |
-| [`@quickswap-defi/sdk`](docs/packages/sdk.md) | V2 entities (`Token`, `Pair`, `Route`, `Trade`), fetcher, router | Published |
+| [`@quickswap-defi/protocol-core`](packages/protocol-core/) | Chain configs, protocol versions, fees, native + stablecoin metadata | Published |
+| [`@quickswap-defi/sdk`](packages/sdk/) | V2 entities (`Token`, `Pair`, `Route`, `Trade`), fetcher, router | Published |
 
 ## How It Works
 
@@ -60,7 +60,7 @@ Documentation follows [Diátaxis](https://diataxis.fr/) — each doc stays in it
 | Doc | Type | Description |
 |-----|------|-------------|
 | [Overview](docs/overview.md) | Explanation | What the SDK is and why the split exists |
-| [Packages](docs/packages/) | Reference | Per-package role, exports, dependencies |
+| [Packages](#packages) | Reference | Per-package READMEs (also published to npm) |
 | [Flows](docs/flows/) | Explanation | Trade execution and chain onboarding |
 | [Diagrams](docs/diagrams/) | Reference | C4 + sequence mermaid sources |
 | [Glossary](docs/glossary.md) | Reference | Domain terms |

packages/protocol-core/README.md

@@ -0,0 +1,64 @@
+# @quickswap-defi/protocol-core
+
+> Pure protocol metadata for QuickSwap — chain registry, protocol versions, fees, native and stablecoin token info. No on-chain calls, no math libraries.
+
+Part of the [QuickSwap-sdk monorepo](https://github.com/QuickSwap/QuickSwap-sdk).
+
+## Install
+
+```bash
+pnpm add @quickswap-defi/protocol-core
+```
+
+## Quickstart
+
+```ts
+import {
+  getChainOrThrow,
+  getSupportedChainIds,
+  computeV2Fee,
+  getStablecoins,
+  getNativeToken,
+} from '@quickswap-defi/protocol-core'
+
+const polygon = getChainOrThrow(137)
+const chains = getSupportedChainIds()
+const native = getNativeToken(137)
+const stables = getStablecoins(137)
+
+const feeAmount = computeV2Fee(1_000_000n) // V2 swap fee in raw units
+```
+
+## Public API
+
+- **Registry** — `CHAIN_REGISTRY`, `CHAIN_ID`, `getChain`, `getChainOrThrow`, `getSupportedChainIds`
+- **Per-chain configs** — `POLYGON`, `BASE`, `MANTRA`, `MANTA`, `SONEIUM`, `SOMNIA`, `IMX`, `XLAYER`, `ZKEVM`, `DOGECHAIN`, `ETHEREUM`
+- **Types** — `ChainConfig`, `ChainProtocolEntry`, `ProtocolVersion`, `SchemaVariant`, `TokenInfo`
+- **Constants** — `PROTOCOL_VERSIONS`, `SCHEMA_VARIANTS`
+- **Protocol helpers** — `getSchemaVariant`, `getSupportedVersions`, `getProtocolVersionLabel`
+- **Fees** — `V2_FEE_BPS`, `V2_FEE_RATE`, `computeV2Fee`
+- **Tokens** — `getNativeToken`, `getWrappedNative`, `getStablecoins`, `getStablecoinAddresses`, `isStablecoin`
+
+## Runtime dependencies
+
+None. TypeScript-only package.
+
+## Consumed by
+
+- [`@quickswap-defi/sdk`](../sdk/) — sibling package that builds the trading layer on top.
+- External consumers (frontends, indexers, analytics) that need protocol metadata without trading logic.
+
+## Status
+
+Published with provenance.
+
+## Documentation
+
+- [Monorepo overview](../../docs/overview.md)
+- [Glossary](../../docs/glossary.md)
+- [Chain onboarding flow](../../docs/flows/chain-onboarding.md)
+- [ADR 001 — protocol-core split](../../docs/adr/001-protocol-core-split.md)
+
+## License
+
+MIT.

packages/sdk/README.md

@@ -0,0 +1,70 @@
+# @quickswap-defi/sdk
+
+> Uniswap V2-fork trading SDK for QuickSwap — `Token`, `Pair`, `Route`, `Trade` entities, fraction-based pricing math, on-chain reserve fetcher, and router calldata helpers.
+
+Part of the [QuickSwap-sdk monorepo](https://github.com/QuickSwap/QuickSwap-sdk).
+
+## Install
+
+```bash
+pnpm add @quickswap-defi/sdk @quickswap-defi/protocol-core
+pnpm add @ethersproject/address @ethersproject/contracts @ethersproject/providers \
+         @ethersproject/networks @ethersproject/solidity
+```
+
+`ethers v5` packages are peer dependencies.
+
+## Quickstart
+
+```ts
+import {
+  ChainId,
+  Token,
+  Fetcher,
+  Route,
+  Trade,
+  TokenAmount,
+  TradeType,
+  Percent,
+} from '@quickswap-defi/sdk'
+
+const USDC = new Token(ChainId.MATIC, '0x2791...', 6, 'USDC', 'USD Coin')
+const WMATIC = new Token(ChainId.MATIC, '0x0d50...', 18, 'WMATIC', 'Wrapped Matic')
+
+const pair = await Fetcher.fetchPairData(USDC, WMATIC, provider)
+const route = new Route([pair], WMATIC)
+const trade = new Trade(route, new TokenAmount(WMATIC, '1000000000000000000'), TradeType.EXACT_INPUT)
+
+const slippage = new Percent('50', '10000') // 0.5%
+const minOut = trade.minimumAmountOut(slippage)
+```
+
+## Public API
+
+- **Entities** — `Token`, `Currency`, `Pair`, `Route`, `Trade`
+- **Fractions** — `Fraction`, `Percent`, `Price`, `CurrencyAmount`, `TokenAmount`
+- **Constants** — `ChainId`, `TradeType`, `Rounding`, `FACTORY_ADDRESS`, `INIT_CODE_HASH`, `MINIMUM_LIQUIDITY`, `JSBI`
+- **Fetcher** — on-chain reserve reads via ethers provider
+- **Router** — swap calldata builders
+- **Errors** — typed error classes for invariant violations
+
+## Dependencies
+
+- [`@quickswap-defi/protocol-core`](../protocol-core/) — sibling, chain registry and protocol metadata.
+- `jsbi`, `big.js`, `decimal.js-light`, `tiny-invariant`, `tiny-warning`, `toformat`.
+- `@ethersproject/*` v5 — peer dependencies.
+
+## Status
+
+Published with provenance.
+
+## Documentation
+
+- [Monorepo overview](../../docs/overview.md)
+- [Glossary](../../docs/glossary.md)
+- [Trade execution flow](../../docs/flows/trade-execution.md)
+- [ADRs](../../docs/adr/)
+
+## License
+
+MIT.