fix(docs): update README and CONTRIBUTING

Author: dineshpinto

CONTRIBUTING.md

@@ -8,6 +8,15 @@ We welcome:
 - [Issues](https://github.com/flare-foundation/developer-hub/issues): Report bugs, propose enhancements, or ask questions.
 - [Pull Requests](https://github.com/flare-foundation/developer-hub/pulls): Fixes, improvements, and new content.
 
+## Prerequisites
+
+- [Node.js v22](https://nodejs.org/en/) and npm
+- Recommended: [nvm](https://github.com/nvm-sh/nvm) to switch Node versions
+- Optional (if editing `examples/`):
+  - Python examples: [uv](https://docs.astral.sh/uv/)
+  - Rust examples: [Cargo](https://doc.rust-lang.org/cargo/)
+  - Go examples: [go](https://go.dev/doc/install)
+
 ## Development workflow
 
 1.  **Fork and branch:** Create a branch that describes the change:
@@ -81,8 +90,6 @@ We welcome:
 
 Run these locally before submitting a PR.
 
-### Site checks
-
 1. **Build (includes internal link validation)**
 
    ```bash
@@ -119,6 +126,27 @@ Run these locally before submitting a PR.
    chmod +x test.sh && ./test.sh
    ```
 
+5. **Automations (only if related files changed)**
+
+   Run this if your change depends on refreshed generated datasets (for example, feeds or contract reference data):
+
+   ```bash
+   npm run automations
+   ```
+
+6. **Solidity docs regeneration (only if `docgen/` or Solidity refs changed)**
+
+   The Solidity docs pipeline currently uses Node 18:
+
+   ```bash
+   nvm use 18
+   cd docgen
+   chmod +x generate-solidity-docs.sh
+   ./generate-solidity-docs.sh
+   cd ..
+   nvm use 22
+   ```
+
 ## <a id="diagrams-style-guide"></a> Diagrams style guide
 
 Use these defaults to keep diagrams consistent across light and dark mode.

README.md

@@ -1,25 +1,17 @@
 # Flare Developer Hub
 
-Source code and content for the [Flare Developer Hub](https://dev.flare.network) - Flare’s documentation site for builders ☀️.
+Source code for the [Flare Developer Hub](https://dev.flare.network), Flare's documentation site built with [Docusaurus](https://docusaurus.io/).
 
-Built with [Docusaurus](https://docusaurus.io/), a modern static site generator.
+If you only want to read the docs, use https://dev.flare.network.
 
-> **Note:**
-> This repository is intended for contributors and maintainers.
-> If you just want to read the docs, visit [dev.flare.network](https://dev.flare.network).
+## Quick start
 
-## Getting started
-
-### Prerequisites
+Prerequisites:
 
 - [Node.js v22](https://nodejs.org/en/) and npm
-  - Recommended: [nvm](https://github.com/nvm-sh/nvm) to manage Node versions
-- (Optional) For language-specific code in [examples](examples/):
-  - Python: [uv](https://docs.astral.sh/uv/)
-  - Rust: [Cargo](https://doc.rust-lang.org/cargo/)
-  - Go: [go](https://go.dev/doc/install)
+- Optional: [nvm](https://github.com/nvm-sh/nvm) for Node version management
 
-### Install and run locally
+Install and run:
 
 ```bash
 git clone https://github.com/flare-foundation/developer-hub.git
@@ -28,114 +20,37 @@ npm ci
 npm run start
 ```
 
-This starts a local development server with hot reloading and opens the site in your browser.
-
-## Repo structure
-
-```plaintext
-flare-foundation/developer-hub/
-├── .github/             # GitHub Actions workflows, issue templates, etc.
-├── automations/         # Scripts + generated data (feeds, addresses, tables).
-├── docgen/              # Tooling for auto-generating Solidity documentation.
-├── docs/                # Core documentation content (MD/MDX).
-├── examples/            # Multi-language examples (Python/Rust/Go/Solidity).
-├── src/                 # Docusaurus custom components, pages, styles, overrides.
-├── static/              # Static assets (images, PDFs, OpenAPI specs).
-├── CONTRIBUTING.md      # Contribution guidelines.
-├── docusaurus.config.ts # Docusaurus site configuration.
-└── sidebars.ts          # Sidebar structure.
-```
-
-## Development workflow
-
-### Build and serve
-
-Some features (for example, search and production-only behavior) only work correctly against a production build.
-
-```bash
-npm run build && npm run serve
-```
-
-- `build` outputs the static site to `build/`
-- `serve` serves the built output locally
-
-### Format
-
-Run [Prettier](https://prettier.io/) for docs and site code:
+For production-like behavior:
 
 ```bash
-npm run format
+npm run build
+npm run serve
 ```
 
-Language-specific examples use their native tooling:
-
-- Go → `gofmt`
-- Rust → `cargo fmt`
-- Python → `ruff format` (and/or `ruff check` depending on the example)
-
-> **Note:**
-> Prettier support for MDXv3 is evolving ([tracking issue](https://github.com/prettier/prettier/issues/12209)).
-> To skip formatting for a section:
->
-> ```plaintext
-> {/* prettier-ignore */}
-> ```
-
-### Run examples
-
-The [`examples/`](examples/) directory contains language-specific projects.
-Each subdirectory includes its own `README.md` with setup and run instructions.
-
-**Supported languages:**
+## Common scripts
 
-- Python
-- JavaScript/TypeScript
-- Rust
-- Go
+- `npm run start`: local dev server with hot reload
+- `npm run build`: production build into `build/`
+- `npm run serve`: serve the production build locally
+- `npm run format`: format docs and site code
+- `npm run lint`: run eslint
+- `npm run typecheck`: run TypeScript checks
+- `npm run automations`: refresh generated data used by docs/components
+- `npm run update-deps`: update dependencies across example projects
 
-### Run automations
+## Repository layout
 
-Automations update generated content used by tables/components (for example, contract addresses and feed metadata).
-This will update `ftso_feeds.json` and `solidity_reference.json` in `src/features/DataTables/*`.
-
-```bash
-npm run automations
-```
-
-To update dependencies across the language example projects:
-
-```bash
-npm run update-deps
-```
-
-> **Caution:**
-> After running update-deps, run the relevant example test/build steps to ensure nothing regressed.
-
-### Generate Solidity documentation
-
-The Solidity doc generator currently requires Node 18.
-
-```bash
-nvm use 18
-cd docgen
-chmod +x generate-solidity-docs.sh
-./generate-solidity-docs.sh
-
-# Return to the main site toolchain
-cd ..
-nvm use 22
-```
-
-This pulls the latest smart contracts and regenerates the Solidity reference docs.
+- `docs/`: documentation content (`.md`/`.mdx`)
+- `src/`: Docusaurus theme overrides, components, and styles
+- `static/`: static assets
+- `examples/`: language-specific example projects
+- `automations/`: scripts and generated datasets
+- `docgen/`: Solidity docs generation tooling
 
 ## Contributing
 
-We welcome contributions of all sizes - from typo fixes to major improvements.
+Contributor workflow, pre-PR checks, PR guidelines, diagram standards, and commit conventions are documented in [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
 
-1. Read [CONTRIBUTING.md](CONTRIBUTING.md).
-2. Create a feature branch:
-   ```bash
-   git checkout -b feat/your-feature-name
-   ```
-3. Make your changes and run the [Pre-PR checks](CONTRIBUTING.md#pre-pr-checks).
-4. Push and open a PR following the [pull request guidelines](CONTRIBUTING.md#pull-request-guidelines).
+This project is licensed under the [MIT License](LICENSE).