docs: add Rust-based README generator

README.md

@@ -1,5 +1,9 @@
 # 🧬 LPKG – Lightweight Package Manager
 
+<p align="center">
+  <img src="assets/logo.svg" alt="LPKG logo" width="360" />
+</p>
+
 LPKG is a minimalistic package manager written in Rust, designed for fast and simple software management on Unix-like systems. It emphasizes reproducibility and declarative configuration, leveraging **Nix Flakes** for development and deployment.
 
 ---
@@ -82,6 +86,29 @@ Build the project:
 cargo build
 ```
 
+LPKG ships with tuned Cargo profiles:
+
+* **Dev builds** (`cargo build`) use `opt-level=0`, lots of codegen units, and incremental compilation for quick feedback while hacking.
+* **Release builds** (`cargo build --release`) enable `-O3`, fat LTO, and panic aborts for slim, fast binaries.
+* **GraphQL builds** add the server components when you need them:
+
+```bash
+cargo build --features graphql
+```
+
+**PGO builds** are a two-step flow using the provided Cargo aliases:
+
+```bash
+# 1) Instrument
+RUSTFLAGS="-Cprofile-generate=target/pgo-data" cargo pgo-instrument
+# run representative workloads to emit *.profraw files under target/pgo-data
+llvm-profdata merge -o target/pgo-data/lpkg.profdata target/pgo-data/*.profraw
+
+# 2) Optimise with the collected profile
+RUSTFLAGS="-Cprofile-use=target/pgo-data/lpkg.profdata -Cllvm-args=-pgo-warn-missing-function" \
+  cargo pgo-build
+```
+
 Run tests:
 
 ```bash
@@ -94,11 +121,33 @@ You can also run the project directly in the flake shell:
 nix run
 ```
 
+## 🕸️ GraphQL API
+
+LPKG now ships a lightweight GraphQL server powered by Actix Web and Juniper.
+
+* Start the server with `cargo run --features graphql --bin graphql_server` (set `LPKG_GRAPHQL_ADDR` to override `127.0.0.1:8080`).
+* Query endpoint: `http://127.0.0.1:8080/graphql`
+* Interactive playground: `http://127.0.0.1:8080/playground`
+
+Example query:
+
+```graphql
+{
+  packages(limit: 5) {
+    name
+    version
+    enableLto
+  }
+  randomJoke {
+    package
+    text
+  }
+}
+```
+
 ### AI metadata tooling
 
-The AI metadata store under `ai/metadata/` comes with a helper CLI to
-validate package records against the JSON schema and regenerate
-`index.json` after adding new entries:
+The AI metadata store under `ai/metadata/` comes with a helper CLI to validate package records against the JSON schema and regenerate `index.json` after adding new entries:
 
 ```bash
 cargo run --bin metadata_indexer -- --base-dir . validate
@@ -107,10 +156,7 @@ cargo run --bin metadata_indexer -- --base-dir . index
 
 Use `--compact` with `index` if you prefer single-line JSON output.
 
-To draft metadata for a specific book page, you can run the harvest mode.
-It fetches the XHTML, scrapes the build commands, and emits a schema-
-compliant JSON skeleton (pass `--dry-run` to inspect the result without
-writing to disk):
+To draft metadata for a specific book page, you can run the harvest mode. It fetches the XHTML, scrapes the build commands, and emits a schema-compliant JSON skeleton (pass `--dry-run` to inspect the result without writing to disk):
 
 ```bash
 cargo run --bin metadata_indexer -- \
@@ -126,8 +172,7 @@ Keep the jhalfs manifests current with:
 cargo run --bin metadata_indexer -- --base-dir . refresh
 ```
 
-Passing `--books mlfs,blfs` restricts the refresh to specific books, and
-`--force` bypasses the local cache.
+Passing `--books mlfs,blfs` restricts the refresh to specific books, and `--force` bypasses the local cache.
 
 To materialise a Rust module from harvested metadata:
 
@@ -142,17 +187,15 @@ Add `--overwrite` to regenerate an existing module directory.
 
 ## 📚 Documentation
 
-- [Architecture Overview](docs/ARCHITECTURE.md) – high-level tour of the crate
-  layout, binaries, and supporting modules.
-- [Metadata Harvesting Pipeline](docs/METADATA_PIPELINE.md) – how the metadata
-  indexer produces and validates the JSON records under `ai/metadata/`.
-- [Package Module Generation](docs/PACKAGE_GENERATION.md) – end-to-end guide
-  for converting harvested metadata into Rust modules under `src/pkgs/by_name/`.
-- `ai/notes.md` – scratchpad for ongoing research tasks (e.g., deeper jhalfs
-  integration).
+* [Architecture Overview](docs/ARCHITECTURE.md) – high-level tour of the crate layout, binaries, and supporting modules.
+* [Metadata Harvesting Pipeline](docs/METADATA_PIPELINE.md) – how the metadata indexer produces and validates the JSON records under `ai/metadata/`.
+* [Package Module Generation](docs/PACKAGE_GENERATION.md) – end-to-end guide for converting harvested metadata into Rust modules under `src/pkgs/by_name/`.
+* Concept corner: [Nixette](concepts/nixette/README.md) – a NixOS × Gentoo transfemme mash-up dreamed up for fun brand explorations.
+* `ai/notes.md` – scratchpad for ongoing research tasks (e.g., deeper jhalfs integration).
 
 ---
 
 ## 📄 License
 
 LPKG is licensed under the [MIT License](LICENSE).
+