docs: update README and documentation for package sizes and JRE details

Author: tae898

README.md

@@ -3,27 +3,32 @@
 Native Python bindings for ArcadeDB (forked from the official Java project).
 
 [![PyPI](https://img.shields.io/pypi/v/arcadedb-embedded)](https://pypi.org/project/arcadedb-embedded/)
-[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/arcadedb-embedded)](https://pypi.org/project/arcadedb-embedded/)
+[![PyPI - Python
+Version](https://img.shields.io/pypi/pyversions/arcadedb-embedded)](https://pypi.org/project/arcadedb-embedded/)
 [![Docs](https://img.shields.io/badge/docs-humem.ai-blue)](https://docs.humem.ai/arcadedb/latest/)
-[![Test Python Bindings](https://github.com/humemai/arcadedb-embedded-python/actions/workflows/test-python-bindings.yml/badge.svg)](https://github.com/humemai/arcadedb-embedded-python/actions/workflows/test-python-bindings.yml)
-[![Test Python Examples](https://github.com/humemai/arcadedb-embedded-python/actions/workflows/test-python-examples.yml/badge.svg)](https://github.com/humemai/arcadedb-embedded-python/actions/workflows/test-python-examples.yml)
-[![Release to PyPI](https://github.com/humemai/arcadedb-embedded-python/actions/workflows/release-python-packages.yml/badge.svg)](https://github.com/humemai/arcadedb-embedded-python/actions/workflows/release-python-packages.yml)
+[![Test Python
+Bindings](https://github.com/humemai/arcadedb-embedded-python/actions/workflows/test-python-bindings.yml/badge.svg)](https://github.com/humemai/arcadedb-embedded-python/actions/workflows/test-python-bindings.yml)
+[![Test Python
+Examples](https://github.com/humemai/arcadedb-embedded-python/actions/workflows/test-python-examples.yml/badge.svg)](https://github.com/humemai/arcadedb-embedded-python/actions/workflows/test-python-examples.yml)
+[![Release to
+PyPI](https://github.com/humemai/arcadedb-embedded-python/actions/workflows/release-python-packages.yml/badge.svg)](https://github.com/humemai/arcadedb-embedded-python/actions/workflows/release-python-packages.yml)
 
 ---
 
 ## ✨ What this repo provides
 
 - Native Python bindings for ArcadeDB with a bundled JRE (no local Java required).
-- Wheels for Linux x86_64, Linux ARM64, and macOS Apple Silicon.
+- **Wheels for Linux x86_64, Linux ARM64, and macOS Apple Silicon.**
 - Embedded usage (in-process) with optional server mode.
 - Tests and examples validated in CI across supported platforms.
 
-The Python bindings and packaging live under bindings/python. The upstream Java project remains the source of the core database.
+The Python bindings and packaging live under bindings/python. The upstream Java project
+remains the source of the core database.
 
 ## 🧱 What’s inside
 
 - bindings/python: Python package source, build scripts, tests, and examples.
-- docs site: https://docs.humem.ai/arcadedb/
+- docs site: [https://docs.humem.ai/arcadedb/](https://docs.humem.ai/arcadedb/)
 - CI: Build/test workflows for bindings and examples (badges above).
 
 ## ✅ Typical use cases
@@ -40,6 +45,7 @@ The Python bindings and packaging live under bindings/python. The upstream Java
 
 ## 📦 What the wheel includes
 
+- Approximate size: ~74MB download, ~101-103MB installed.
 - Lightweight Java 25 runtime (jlink) bundled per platform.
 - ArcadeDB JARs required for the embedded engine.
 - Python bindings and source modules.
@@ -56,12 +62,15 @@ The Python bindings and packaging live under bindings/python. The upstream Java
 uv pip install arcadedb-embedded
 ```
 
-See [the Python README](https://github.com/humemai/arcadedb-embedded-python/blob/main/bindings/python/README.md) for usage, examples, and build details.
+See [the Python
+README](bindings/python/README.md)
+for usage, examples, and build details.
 
 ## 🔗 Quick Links
 
-- Python README: https://github.com/humemai/arcadedb-embedded-python/blob/main/bindings/python/README.md
-- PyPI: https://pypi.org/project/arcadedb-embedded/
+- Python README: [bindings/python/README.md](bindings/python/README.md)
+- PyPI:
+  [https://pypi.org/project/arcadedb-embedded/](https://pypi.org/project/arcadedb-embedded/)
 
 ## 🔄 Syncing Upstream
 
@@ -74,20 +83,23 @@ This fork tracks ArcadeData/arcadedb through the local `upstream-main` mirror br
 The sync keeps this fork's root `README.md`, `CLAUDE.md`, and the removed Java/Maven
 workflows under `.github/workflows/` from being overwritten or reintroduced, including
 the removed `meterian.yml` workflow. See the full sync notes in
-`bindings/python/docs/development/sync-upstream.md`.
+[bindings/python/docs/development/sync-upstream.md](bindings/python/docs/development/sync-upstream.md).
 
 ## 🧭 Upstream ArcadeDB (Java)
 
 This repo is a fork of ArcadeDB Java. For the server, Java API, and core database docs:
 
-- Upstream repo: https://github.com/ArcadeData/arcadedb
-- Docs: https://docs.arcadedb.com
+- Upstream repo:
+  [https://github.com/ArcadeData/arcadedb](https://github.com/ArcadeData/arcadedb)
+- Docs: [https://docs.arcadedb.com](https://docs.arcadedb.com)
 
 ## 💬 Support & community
 
-- Issues (Python bindings): https://github.com/humemai/arcadedb-embedded-python/issues
-- ArcadeDB Discord: https://discord.gg/w2Npx2B7hZ
+- Issues (Python bindings):
+  [https://github.com/humemai/arcadedb-embedded-python/issues](https://github.com/humemai/arcadedb-embedded-python/issues)
+- ArcadeDB Discord: [https://discord.gg/w2Npx2B7hZ](https://discord.gg/w2Npx2B7hZ)
 
 ## 📄 License
 
-Both upstream ArcadeDB (Java) and this ArcadeDB Embedded Python project are licensed under Apache 2.0, fully open and free for everyone, including commercial use.
+Both upstream ArcadeDB (Java) and this ArcadeDB Embedded Python project are licensed
+under Apache 2.0, fully open and free for everyone, including commercial use.

bindings/python/docs/development/build-architecture.md

@@ -6,21 +6,21 @@ This document describes the build architecture for creating platform-specific Py
 
 **Goal:** Distribute a single `arcadedb-embedded` package that works on 4 platforms with **zero Java installation required**.
 
-**Achievement:** 4 platform-specific wheels (currently about 70-75MB compressed, depending on platform and version) with bundled platform-specific JRE, built and tested on GitHub Actions using native runners.
+**Achievement:** 4 platform-specific wheels (currently about ~74MB compressed and ~101MB installed on Linux x86_64, with slight platform/version variation) with bundled platform-specific JRE, built and tested on GitHub Actions using native runners.
 
 ## Supported Platforms
 
 | Platform | Wheel Size | JRE Size | Runner | Build Method | Notes |
 |----------|-----------|----------|---------|--------------|-------|
-| **linux/amd64** | ~73M | ~60M | `ubuntu-24.04` | Docker native | Most common Linux platform |
-| **linux/arm64** | ~70-75M | ~60M | `ubuntu-24.04-arm` | Docker native | ARM64 servers, Raspberry Pi |
-| **darwin/arm64** | ~70-75M | ~60M | `macos-15` | Native build | Apple Silicon Macs (2020+) |
-| **windows/amd64** | ~70-75M | ~60M | `windows-2025` | Native build | Windows x86_64 |
+| **linux/amd64** | ~74M | ~63M | `ubuntu-24.04` | Docker native | Most common Linux platform |
+| **linux/arm64** | ~70-75M | ~63M | `ubuntu-24.04-arm` | Docker native | ARM64 servers, Raspberry Pi |
+| **darwin/arm64** | ~70-75M | ~63M | `macos-15` | Native build | Apple Silicon Macs (2020+) |
+| **windows/amd64** | ~70-75M | ~63M | `windows-2025` | Native build | Windows x86_64 |
 
 **All supported platforms:**
 
 - ✅ Current suite: 331 passed
-- ✅ 31.7M JARs (83 files, identical across platforms)
+- ✅ ~38M JARs (current Linux x86_64 package info, identical contents across platforms)
 - ✅ All native runners (no QEMU emulation)
 - ✅ Reproducible builds (pinned runner versions)
 
@@ -388,14 +388,14 @@ bindings/python/
 
 **Solution:** Switch to JUnit XML (structured data, no regex).
 
-## Size Breakdown (current, as of 17-Mar-2026)
+## Size Breakdown (current ballpark)
 
 Sizes are ballpark values and vary by platform and version:
 
-- Wheel: ~70-75M (compressed)
-- JRE: ~60M (uncompressed)
-- JARs: ~32M (uncompressed)
-- Installed package: ~100-105M
+- Wheel: ~74M (compressed)
+- JRE: ~63M (uncompressed)
+- JARs: ~38M (uncompressed)
+- Installed package: ~101-103M
 
 ## Development
 

bindings/python/docs/development/ci-setup.md

@@ -8,7 +8,7 @@ The CI/CD workflows now support building and releasing across **4 platforms** fo
 
 ### Single-Package Strategy
 
-- **arcadedb-embedded**: All platforms (~70-75MB compressed, depending on platform and version) - JRE bundled, no external Java needed
+- **arcadedb-embedded**: All platforms (~74MB compressed and ~101MB installed on current Linux x86_64 builds; varies slightly by platform and version) - JRE bundled, no external Java needed
 
 ### Platforms (All Native Runners)
 
@@ -102,12 +102,12 @@ All 4 platforms passing the bindings suite and example workflows:
 
 | Platforms | Wheel Size | JRE Size | Tests |
 |-----------|-----------|----------|-------|
-| linux/amd64, linux/arm64, darwin/arm64, windows/amd64 | ~70-75M | ~60M | 331 passed ✅ |
+| linux/amd64, linux/arm64, darwin/arm64, windows/amd64 | ~74M | ~63M | 331 passed ✅ |
 
 **All platforms include:**
 
-- 32.4M JARs (83 files, identical across platforms, gRPC excluded)
-- Platform-specific JRE (~60M uncompressed, similar across platforms)
+- ~38M JARs (current Linux x86_64 package info, same contents across platforms, gRPC excluded)
+- Platform-specific JRE (~63M uncompressed, similar across platforms)
 - Native runners (no QEMU emulation anywhere)
 
 ## Cross-Platform Building

bindings/python/docs/getting-started/distributions.md

@@ -6,7 +6,7 @@ ArcadeDB Python provides a **self-contained embedded** package that runs the dat
 
 | Package | Wheel Size | Installed Size | Java Required | Studio UI | Query Languages |
 |---------|-----------|------------------------------|---------------|-----------|----------------|
-| **arcadedb-embedded** | ~70-75MB | ~100-105MB | ❌ No | ✅ | SQL, OpenCypher, MongoDB |
+| **arcadedb-embedded** | ~74MB | ~101-103MB | ❌ No | ✅ | SQL, OpenCypher, MongoDB |
 
 **Installation:**
 
@@ -20,17 +20,17 @@ uv pip install arcadedb-embedded
 
 The package includes everything you need:
 
-- **ArcadeDB JARs** (~32MB, uncompressed): Core database with all features
-- **Bundled JRE** (~60MB, uncompressed): Platform-specific Java 25 runtime (via jlink)
+- **ArcadeDB JARs** (~38MB, uncompressed): Core database with all features
+- **Bundled JRE** (~63MB, uncompressed): Platform-specific Java 25 runtime (via jlink)
 
-**Current Linux x86_64 dev build:** ~73MB compressed wheel, ~102MB installed package size.
+**Current Linux x86_64 package info:** ~74MB compressed wheel, ~63MB JRE, ~38MB JARs, and ~101MB installed. Local installs may show closer to ~103MB on disk depending on filesystem allocation.
 
 These numbers are measured from the built wheel file and the extracted
 `site-packages/arcadedb_embedded/` directory, and they vary by platform and version.
 
 ## Platform Support
 
-Pre-built **platform-specific** wheels are available for **4 platforms**. Sizes are consistent across platforms (see size breakdown below).
+Pre-built **platform-specific** wheels are available for **4 platforms**. Sizes stay in the same ballpark across platforms, but vary slightly by platform and version (see size breakdown below).
 
 **Key Features:**
 
@@ -44,7 +44,7 @@ Pre-built **platform-specific** wheels are available for **4 platforms**. Sizes
 
 **Core Features:**
 
-- ✅ **No Java Installation Required**: Platform-specific JRE bundled (~60MB uncompressed)
+- ✅ **No Java Installation Required**: Platform-specific JRE bundled (~63MB uncompressed)
 - ✅ **Core Database**: All models (Graph, Document, Key/Value, Vector, Time Series)
 - ✅ **Query Languages**: SQL, OpenCypher, MongoDB (all included)
 - ✅ **Studio Web UI**: Visual database explorer and query editor
@@ -110,16 +110,16 @@ Simple and consistent across all platforms!
 
 ## Size Breakdown
 
-Current sizes are ballpark values and can move with ArcadeDB, the bundled JRE, and the
-target platform:
+Current sizes are ballpark values and can move with ArcadeDB, the bundled JRE, the
+target platform, and filesystem overhead after installation:
 
-- **Wheel (compressed)**: ~70-75MB
-- **Installed package**: ~100-105MB
+- **Wheel (compressed)**: ~74MB
+- **Installed package**: ~101-103MB
 
 **Components (uncompressed):**
 
-- **ArcadeDB JARs**: ~31.7MB
-- **Bundled JRE**: ~60MB (platform-specific Java 25 runtime via jlink)
+- **ArcadeDB JARs**: ~38MB
+- **Bundled JRE**: ~63MB (platform-specific Java 25 runtime via jlink)
 
 **Optimizations:**
 

bindings/python/docs/getting-started/installation.md

@@ -18,12 +18,12 @@ uv pip install arcadedb-embedded
 
 ## What's Included
 
-The `arcadedb-embedded` package includes everything you need. Current Linux x86_64 dev
-builds are about 73MB as a wheel and about 102MB installed, with some variation by
-platform and version:
+The `arcadedb-embedded` package includes everything you need. Current Linux x86_64
+package metadata and local installs are about ~74MB as a wheel and ~101-103MB
+installed, with some variation by platform, version, and filesystem allocation:
 
-- **ArcadeDB JARs**: ~31.7MB (uncompressed)
-- **Bundled JRE**: ~60MB (uncompressed, platform-specific Java 25 runtime via jlink)
+- **ArcadeDB JARs**: ~38MB (uncompressed)
+- **Bundled JRE**: ~63MB (uncompressed, platform-specific Java 25 runtime via jlink)
 
 **Features Included:**
 

bindings/python/docs/index.md

@@ -171,7 +171,7 @@ We provide a **single, self-contained package** that works on all major platform
 
 | Platforms | Package Name | Size | What's Included |
 |----------|-------------|------|-----------------|
-| linux/amd64, linux/arm64, darwin/arm64, windows/amd64 | `arcadedb-embedded` | ~70-75MB | Full ArcadeDB + Bundled JRE + Studio UI |
+| linux/amd64, linux/arm64, darwin/arm64, windows/amd64 | `arcadedb-embedded` | ~74MB wheel, ~101-103MB installed | Full ArcadeDB + Bundled JRE + Studio UI |
 
 The package uses the standard import:
 
@@ -211,13 +211,18 @@ import arcadedb_embedded as arcadedb
 - **OS**: Linux (x86_64, ARM64), macOS (Apple Silicon), or Windows (x86_64)
 
 !!! note "Self-Contained"
-    Everything needed to run ArcadeDB is included in the wheel (currently about
-    73MB on Linux x86_64; varies by platform and version):
+    Everything needed to run ArcadeDB is included in the wheel. Current Linux
+    x86_64 package metadata and local installs are in this ballpark, with small
+    variation by platform, version, and filesystem:
 
     - **Bundled JRE**
-    (Platform-specific Java 25 runtime trimmed with jlink to only what's required for ArcadeDB, ~60MB uncompressed)
+    (Platform-specific Java 25 runtime trimmed with jlink to only what's required for ArcadeDB, ~63MB uncompressed)
     - **ArcadeDB JARs**
-    (~32MB uncompressed)
+    (~38MB uncompressed)
+    - **Wheel download**
+    (~74MB compressed)
+    - **Installed package on disk**
+    (~101-103MB)
     - **JPype** (Bridge between Python and the bundled JVM)
 
 ## Community & Support