Rework README

AGENTS.md

@@ -0,0 +1,44 @@
+# AGENTS.md
+
+Source of the API3 documentation at https://docs.api3.org, built with VitePress. Content is Markdown under `docs/`, one directory per section, each with its own `sidebar.js`. Sections are registered in `docs/.vitepress/config.js`. [CONTRIBUTING.md](./CONTRIBUTING.md) is the full contributor guide.
+
+## Commands
+
+```sh
+pnpm install
+pnpm docs:dev
+pnpm format
+pnpm lint
+pnpm docs:build
+```
+
+`pnpm format` formats the whole project with Prettier. Never hand-format. `pnpm docs:build` regenerates `docs/public/llms.txt` and `llms-full.txt` before building.
+
+Link validation, the same check CI runs:
+
+```sh
+pnpm docs:build
+pnpm docs:serve &
+node ./libs/link-validator.js http://localhost:8082 ./docs/.vitepress/dist/
+```
+
+## Content rules
+
+- Every page listed in a sidebar declares `title` and `pageHeader` in its frontmatter and starts its body with `<PageHeader/>`. A missing `<PageHeader/>` fails the build.
+- A new page goes into the section's `sidebar.js`. A new section needs its own directory with a `sidebar.js` and entries in `config.js` under both `sidebar` and `nav`.
+- Images live next to the page that uses them. Anything linked by URL from prose goes in `docs/public`.
+- `docs/public/llms.txt` and `llms-full.txt` are generated and gitignored. Never edit them.
+- Verify numbers, addresses and quoted CLI output against their source, such as the `api3dao/contracts` repository, on-chain state or API3 Market, before changing them.
+
+## Writing rules
+
+- Write API3 in capitals. Lowercase `api3` only in identifiers: package names, paths, URLs and the logo wordmark. Contract names such as `Api3ReaderProxyV1` and deployed product names such as the `Api3 Core` vault keep their own spelling.
+- `dAPI` and `dApp` in prose, `dapi` and `dapp` in code identifiers.
+- Hyphens instead of long dashes. No semicolons in prose.
+- Name the acting entity, such as API3 or the Market frontend, rather than writing "we" in new text.
+- Do not write facts that the next change turns false: exact counts of things that grow, closed-world claims about a set, or lists that need an edit whenever an entry appears. Link to the source instead.
+
+## Pull requests
+
+- Target `main` and reference the issue in the description, for example `Closes #1`.
+- CI runs `pnpm lint`, `pnpm docs:build` and the link validator. Every pull request gets a Firebase preview deployment.

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

CONTRIBUTING.md

@@ -1,29 +1,46 @@
-# Contributors' guide
+# Contributing
 
-Welcome to the API3 documentation repository. This guide will help you get
-started with contributing to the API3 documentation. The docs use [VitePress](https://vitepress.dev/), a Vue-powered static
-site generator. Follow the steps below to get started.
+The docs are a [VitePress](https://vitepress.dev/) site. Content is Markdown under [`docs/`](./docs), one directory per top-level section, and each section owns the `sidebar.js` that defines its navigation. Sections are registered in [`docs/.vitepress/config.js`](./docs/.vitepress/config.js), which the `llms.txt` generator reads too. The landing page is [`docs/index.md`](./docs/index.md).
 
-## Submitting an issue
+## Local setup
 
-You can submit an issue if you find any bugs or have any feature requests.
-Please make sure to check if the issue already exists before submitting a new
-one.
+```sh
+pnpm install
+pnpm docs:dev
+```
 
-## Making a pull request
+`pnpm docs:build` writes the production build to `docs/.vitepress/dist` and `pnpm docs:serve` serves that build locally.
 
-After making changes in a feature branch, submit a pull request (PR) against the `main` branch.
-Make sure to link the corresponding GitHub Issue in the PR description e.g.
-`Closes #1`. You will be able to see the changes within a Firebase preview
-deployment that is unique to the PR. The PR will be reviewed by the team and
-merged into the `main` branch, which will result in the changes going live into
-production.
+Both `docs:dev` and `docs:build` first run [`scripts/generate-llms-files.js`](./scripts/generate-llms-files.js), which writes `llms.txt` and `llms-full.txt` into `docs/public` from the section sidebars. Both files are gitignored. Do not edit them by hand.
 
-### Getting started
+## Writing a page
 
-After cloning the repo locally, install the dependencies and run the docs locally.
+- Start the frontmatter with `title` and `pageHeader`, and the body with `<PageHeader/>`. The generator reads the frontmatter for the page headings and fails the build when `<PageHeader/>` is missing.
+- Add the page to the section's `sidebar.js`. A new section needs its own directory with a `sidebar.js`, plus an entry in `config.js` under both `sidebar` and `nav`.
+- Put images next to the page that uses them. Anything linked by URL from prose goes in `docs/public`, so its path stays stable across builds.
+- Write API3 in capitals. Lowercase `api3` is only for identifiers such as package names, paths and URLs, and for the logo wordmark. Contract names such as `Api3ReaderProxyV1` and deployed product names such as the `Api3 Core` vault keep their own spelling.
+- Use `dAPI` and `dApp` in prose, `dapi` and `dapp` in code identifiers.
+- Use hyphens rather than long dashes, and avoid semicolons in prose.
+- Keep pages high level and link to the authoritative source, such as a repository, a contract or API3 Market, instead of duplicating detail that goes stale.
 
-```bash
-pnpm install
-pnpm docs:dev
+## Checks
+
+Prettier is the only formatter. `pnpm format` formats the whole project and `pnpm format:check` verifies it. The husky pre-push hook runs the check.
+
+VitePress dead link detection is disabled in the config on purpose. CI builds the site, serves it and checks every internal and external link, including anchors, with [`libs/link-validator.js`](./libs/link-validator.js). Reproduce it locally with:
+
+```sh
+pnpm docs:build
+pnpm docs:serve &
+node ./libs/link-validator.js http://localhost:8082 ./docs/.vitepress/dist/
 ```
+
+Hosts that block automated requests are listed in [`libs/link-validator-ignore.json`](./libs/link-validator-ignore.json).
+
+## Issues and pull requests
+
+Check the existing issues before opening a new one. Open pull requests against `main` and reference the issue in the description, for example `Closes #1`. CI runs the format check, the build and the link validator on every pull request, and the preview workflow posts a link to a Firebase preview of the site. Merging to `main` deploys the live site.
+
+## Deployment
+
+The site is hosted on Firebase Hosting under the project named in [`.firebaserc`](./.firebaserc). The [live workflow](./.github/workflows/firebase-live.yml) deploys every push to `main`, and the [preview workflow](./.github/workflows/firebase-preview.yml) deploys an expiring preview channel for every pull request.

README.md

@@ -1,40 +1,32 @@
-# API3 documentation
-
-> Source of the API3 documentation published at https://docs.api3.org
-
-The site is built with [VitePress](https://vitepress.dev/). Content lives under [`docs/`](./docs), one directory per top-level section. Each section owns its `sidebar.js` and is registered in [`docs/.vitepress/config.js`](./docs/.vitepress/config.js), which the llms generator reads too. The landing page is [`docs/index.md`](./docs/index.md).
-
-## Development
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/public/img/Api3_Docs-Logo-Primary-Light.svg">
+    <img alt="API3 documentation" src="docs/public/img/Api3_Docs-Logo-Primary-Dark.svg" width="360">
+  </picture>
+</p>
 
-```sh
-pnpm install
-pnpm docs:dev
-```
-
-`pnpm docs:build` produces the production build in `docs/.vitepress/dist` and `pnpm docs:serve` serves it locally.
+# API3 documentation
 
-Prettier is the only formatter. Run `pnpm format` to format the whole project and `pnpm format:check` to verify. The husky pre-push hook runs the check, and CI runs it again on every pull request.
+> Source of the API3 documentation published at [docs.api3.org](https://docs.api3.org).
 
-## Generated files
+## Contents
 
-`docs:dev` and `docs:build` first run [`scripts/generate-llms-files.js`](./scripts/generate-llms-files.js), which writes `llms.txt` and `llms-full.txt` into `docs/public` from the section sidebars. Both files are gitignored. The generator reads the `title` and `pageHeader` frontmatter of every page listed in a sidebar and requires the page body to start with `<PageHeader/>`, failing the build otherwise.
+New to API3 data feeds? Start with the [Quickstart](https://docs.api3.org/dapps/quickstart/).
 
-## Link validation
+- **[dApps](https://docs.api3.org/dapps/)**: activating a data feed on [API3 Market](https://market.api3.org), reading it from a contract through `Api3ReaderProxyV1`, integration and security considerations, and how OEV Rewards pay dApps for using the feeds.
+- **[OEV](https://docs.api3.org/oev/)**: what Oracle Extractable Value is, how API3 data feeds and OEV feeds work at the contract level, and how searchers use the public Signed APIs.
+- **[Curation](https://docs.api3.org/curation/)**: the Morpho vaults API3 curates, their roles and operations, risk management and disclosure.
 
-VitePress dead link detection is disabled in the config on purpose. CI instead builds the site, serves it and checks every internal and external link, including anchors, with [`libs/link-validator.js`](./libs/link-validator.js). Reproduce it locally with:
+## AI assistants
 
-```sh
-pnpm docs:build
-pnpm docs:serve &
-node ./libs/link-validator.js http://localhost:8082 ./docs/.vitepress/dist/
-```
+The site publishes an [`llms.txt`](https://docs.api3.org/llms.txt) index and an [`llms-full.txt`](https://docs.api3.org/llms-full.txt) file with the full content of every page, following the [llms.txt convention](https://llmstxt.org/). Paste one of them into a chat, or reference it from your project's agent instructions such as `AGENTS.md`, `CLAUDE.md` or `.cursor/rules`, to give an assistant current context on API3.
 
-Hosts that block automated requests are listed in [`libs/link-validator-ignore.json`](./libs/link-validator-ignore.json).
+Coding agents working on this repository read [AGENTS.md](./AGENTS.md).
 
-## Deployment
+## Contributing
 
-The site is hosted on Firebase Hosting under the project named in [`.firebaserc`](./.firebaserc). The [live workflow](./.github/workflows/firebase-live.yml) deploys every push to `main`, and the [preview workflow](./.github/workflows/firebase-preview.yml) deploys an expiring preview channel for every pull request.
+Issues and pull requests are welcome. [CONTRIBUTING.md](./CONTRIBUTING.md) covers the local setup, page conventions, checks and the deployment flow. Questions go to the [API3 Discord](https://discord.gg/api3dao).
 
-## Contributing
+## License
 
-Head to [CONTRIBUTING.md](./CONTRIBUTING.md) for the issue and pull request workflow.
+[MIT](./LICENSE). The documentation content is subject to the [API3 terms and conditions](https://api3.org/terms-and-conditions/).