nibula 1.2.4 → 1.2.6

package/LICENSE

@@ -1,170 +1,170 @@
-Apache License
-                           Version 2.0, January 2004
-                        http://www.apache.org/licenses/
-
-   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
-
-   1. Definitions.
-
-      "License" shall mean the terms and conditions for use, reproduction,
-      and distribution as defined by Sections 1 through 9 of this document.
-
-      "Licensor" shall mean the copyright owner or entity authorized by
-      the copyright owner that is granting the License.
-
-      "Legal Entity" shall mean the union of the acting entity and all
-      other entities that control, are controlled by, or are under common
-      control with that entity. For the purposes of this definition,
-      "control" means (i) the power, direct or indirect, to cause the
-      direction or management of such entity, whether by contract or
-      otherwise, or (ii) ownership of fifty percent (50%) or more of the
-      outstanding shares, or (iii) beneficial ownership of such entity.
-
-      "You" (or "Your") shall mean an individual or Legal Entity
-      exercising permissions granted by this License.
-
-      "Source" form shall mean the preferred form for making modifications,
-      including but not limited to software source code, documentation
-      source, and configuration files.
-
-      "Object" form shall mean any form resulting from mechanical
-      transformation or translation of a Source form, including but
-      not limited to compiled object code, generated documentation,
-      and conversions to other media types.
-
-      "Work" shall mean the work of authorship, whether in Source or
-      Object form, made available under the License, as indicated by a
-      copyright notice that is included in or attached to the work
-      (an example is provided in the Appendix below).
-
-      "Derivative Works" shall mean any work, whether in Source or Object
-      form, that is based on (or derived from) the Work and for which the
-      editorial revisions, annotations, elaborations, or other
-      modifications represent, as a whole, an original work of authorship.
-      For the purposes of this License, Derivative Works shall not include
-      works that remain separable from, or merely link (or bind by name)
-      to the interfaces of, the Work and Derivative Works thereof.
-
-      "Contribution" shall mean, as submitted to the Licensor for inclusion
-      in the Work by the copyright owner or by an individual or Legal Entity
-      authorized to submit on behalf of the copyright owner. For the
-      purposes of this definition, "submitted" means any form of electronic,
-      verbal, or written communication sent to the Licensor or its
-      representatives, including but not limited to communication on
-      electronic mailing lists, source code control systems, and issue
-      tracking systems that are managed by, or on behalf of, the Licensor
-      for the purpose of discussing and improving the Work, but excluding
-      communication that is conspicuously marked or otherwise designated
-      in writing by the copyright owner as "Not a Contribution."
-
-      "Contributor" shall mean Licensor and any Legal Entity on behalf of
-      whom a Contribution has been received by the Licensor and incorporated
-      within the Work.
-
-   2. Grant of Copyright License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      copyright license to reproduce, prepare Derivative Works of,
-      publicly display, publicly perform, sublicense, and distribute the
-      Work and such Derivative Works in Source or Object form.
-
-   3. Grant of Patent License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      (except as stated in this section) patent license to make, have made,
-      use, offer to sell, sell, import, and otherwise transfer the Work,
-      where such license applies only to those patent claims licensable
-      by such Contributor that are necessarily infringed by their
-      Contribution(s) alone or by combination of their Contribution(s)
-      with the Work to which such Contribution(s) was submitted. If You
-      institute patent litigation against any entity (including a
-      cross-claim or counterclaim in a lawsuit) alleging that the Work
-      or a Contribution incorporated within the Work constitutes direct
-      or contributory patent infringement, then any patent licenses
-      granted to You under this License for that Work shall terminate
-      as of the date such litigation is filed.
-
-   4. Redistribution. You may reproduce and distribute copies of the
-      Work or Derivative Works thereof in any medium, with or without
-      modifications, and in Source or Object form, provided that You
-      meet the following conditions:
-
-      (a) You must give any other recipients of the Work or Derivative
-          Works a copy of this License; and
-
-      (b) You must cause any modified files to carry prominent notices
-          stating that You changed the files; and
-
-      (c) You must retain, in the Source form of any Derivative Works
-          that You distribute, all copyright, patent, trademark, and
-          attribution notices from the Source form of the Work,
-          excluding those notices that do not pertain to any part of
-          the Derivative Works; and
-
-      (d) If the Work includes a NOTICE text file, You must include a
-          readable copy of the attribution notices contained within such
-          NOTICE file, in at least one of the following places: within
-          a NOTICE text file distributed as part of the Derivative Works;
-          within the Source form or documentation, if provided along with
-          the Derivative Works; or, within a display generated by the
-          Derivative Works, if and wherever such third-party notices
-          normally appear. The contents of the NOTICE file are for
-          informational purposes only and do not modify the License.
-
-   5. Submission of Contributions. Unless You explicitly state otherwise,
-      any Contribution intentionally submitted for inclusion in the Work
-      by You to the Licensor shall be under the terms and conditions of
-      this License, without any additional terms or conditions.
-
-   6. Trademarks. This License does not grant permission to use the trade
-      names, trademarks, service marks, or product names of the Licensor,
-      except as required for reasonable and customary use in describing the
-      origin of the Work and reproducing the content of the NOTICE file.
-
-   7. Disclaimer of Warranty. Unless required by applicable law or agreed
-      to in writing, Licensor provides the Work (and each Contributor
-      provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES
-      OR CONDITIONS OF ANY KIND, either express or implied, including,
-      without limitation, any warranties or conditions of TITLE,
-      NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR
-      PURPOSE. You are solely responsible for determining the
-      appropriateness of using or reproducing the Work and assume any
-      risks associated with Your exercise of permissions under this License.
-
-   8. Limitation of Liability. In no event and under no legal theory,
-      whether in tort (including negligence), contract, or otherwise,
-      unless required by applicable law (such as deliberate and grossly
-      negligent acts) or agreed to in writing, shall any Contributor be
-      liable to You for damages, including any direct, indirect, special,
-      incidental, or exemplary damages of any character arising as a
-      result of this License or out of the use or inability to use the
-      Work (including but not limited to damages for loss of goodwill,
-      work stoppage, computer failure or malfunction, or all other
-      commercial damages or losses), even if such Contributor has been
-      advised of the possibility of such damages.
-
-   9. Accepting Warranty or Liability While Redistributing. You may choose
-      to offer, and charge a fee for, acceptance of support, warranty,
-      indemnity, or other liability obligations and/or rights consistent
-      with this License. However, in accepting such obligations, You may
-      act only on Your own behalf and on Your sole responsibility, not on
-      behalf of any other Contributor, and only if You agree to indemnify,
-      defend, and hold each Contributor harmless for any liability incurred
-      by, or claims asserted against, such Contributor by reason of your
-      accepting any such warranty or additional liability.
-
-   END OF TERMS AND CONDITIONS
-
-   Copyright 2026 Michele Garofalo
-
-   Licensed under the Apache License, Version 2.0 (the "License");
-   you may not use this file except in compliance with the License.
-   You may obtain a copy of the License at
-
-       http://www.apache.org/licenses/LICENSE-2.0
-
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
-   implied. See the License for the specific language governing
+Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other
+      modifications represent, as a whole, an original work of authorship.
+      For the purposes of this License, Derivative Works shall not include
+      works that remain separable from, or merely link (or bind by name)
+      to the interfaces of, the Work and Derivative Works thereof.
+
+      "Contribution" shall mean, as submitted to the Licensor for inclusion
+      in the Work by the copyright owner or by an individual or Legal Entity
+      authorized to submit on behalf of the copyright owner. For the
+      purposes of this definition, "submitted" means any form of electronic,
+      verbal, or written communication sent to the Licensor or its
+      representatives, including but not limited to communication on
+      electronic mailing lists, source code control systems, and issue
+      tracking systems that are managed by, or on behalf of, the Licensor
+      for the purpose of discussing and improving the Work, but excluding
+      communication that is conspicuously marked or otherwise designated
+      in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any Legal Entity on behalf of
+      whom a Contribution has been received by the Licensor and incorporated
+      within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a NOTICE text file, You must include a
+          readable copy of the attribution notices contained within such
+          NOTICE file, in at least one of the following places: within
+          a NOTICE text file distributed as part of the Derivative Works;
+          within the Source form or documentation, if provided along with
+          the Derivative Works; or, within a display generated by the
+          Derivative Works, if and wherever such third-party notices
+          normally appear. The contents of the NOTICE file are for
+          informational purposes only and do not modify the License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or agreed
+      to in writing, Licensor provides the Work (and each Contributor
+      provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES
+      OR CONDITIONS OF ANY KIND, either express or implied, including,
+      without limitation, any warranties or conditions of TITLE,
+      NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR
+      PURPOSE. You are solely responsible for determining the
+      appropriateness of using or reproducing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or exemplary damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or all other
+      commercial damages or losses), even if such Contributor has been
+      advised of the possibility of such damages.
+
+   9. Accepting Warranty or Liability While Redistributing. You may choose
+      to offer, and charge a fee for, acceptance of support, warranty,
+      indemnity, or other liability obligations and/or rights consistent
+      with this License. However, in accepting such obligations, You may
+      act only on Your own behalf and on Your sole responsibility, not on
+      behalf of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability incurred
+      by, or claims asserted against, such Contributor by reason of your
+      accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 Michele Garofalo
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied. See the License for the specific language governing
    permissions and limitations under the License.

package/NOTICE

@@ -1,5 +1,5 @@
-Nibula
-Copyright 2026 Michele Garofalo
-
-This product includes software developed by Michele Garofalo.
+Nibula
+Copyright 2026 Michele Garofalo
+
+This product includes software developed by Michele Garofalo.
 https://github.com/Rhaastrake/Nibula

package/README.md

@@ -1,123 +1,120 @@
-# ✏️ Nibula
-
-**Nibula** is an open source static site generator built on top of [Eleventy](https://www.11ty.dev/), with one clear mission: make the jump from plain, hand-written websites to a real project setup as gentle as possible — without ever pulling you away from the web you already know.
-
-If you've only ever written HTML, CSS, and a bit of JavaScript, moving to a "framework" usually feels like starting over: new syntax, new rules, new folder structures, and a pile of documentation before you can even see a page on screen. Nibula is designed to avoid exactly that. You keep working with the **three languages that matter — HTML, CSS, and JavaScript** — and the tool quietly handles the tedious parts around them. The goal is simple: even someone with little experience should always know *where to put their hands*.
-
-It's a great fit for **showcase and brochure-style websites** (portfolios, landing pages, small business sites), where you want something clean and fast without dragging in a heavy framework.
-
-### ✨ Why Nibula?
-
-Building a website from scratch involves a lot of moving parts: templating, build steps, SEO files, server config, project structure. Nibula takes care of all of that for you, so you can focus on what actually matters — **your content and your ideas** — while still learning skills that transfer anywhere on the web.
-
-- 🔧 **Zero-config ready** — install, create, and you're live in minutes
-- 🧭 **Stays close to vanilla** — real HTML, CSS, and JS, so nothing you learn goes to waste
-- 🔎 **SEO made simple** — managed from one central place; `sitemap`, `llms.txt`, and `robots.txt` are generated automatically
-- 🖱️ **A helpful CLI** — create a page with one command instead of hand-writing ten separate files
-- ⚙️ **Server configs handled for you** — `.htaccess` and `web.config` are generated automatically, and an `nginx.conf` is provided so that anyone comfortable with nginx already has what they need to run the site outside of shared hosting
-- 🎨 **Pick your CSS framework** — choose from 4 pre-installed options (or none), and switch later in a few guided steps
-- 🔌 **Pick your backend** — Node.js or PHP, chosen at creation; **Composer is only needed for PHP**
-- 🧩 **Your own modules** — add your own CSS and JS/TS modules freely and easily
-- 🪶 **Lightweight by default** — SCSS frameworks can be filtered so you ship only what you actually use
-- 🌍 **Open source** — free to use, free to modify, free to share
-
-![Version](https://img.shields.io/badge/version-1.2.4-blue)
-![License](https://img.shields.io/badge/license-Apache--2.0-blue)
-![Eleventy](https://img.shields.io/badge/11ty-v3.1.2-black)
-
-## JavaScript or TypeScript — your choice
-
-When you create a project, you decide how you want to work:
-
-- **JavaScript** — the simplest path, ideal if you're still getting comfortable.
-- **TypeScript** — for more experienced users who want stronger typing and tooling.
-
-Either way, the project structure stays the same, so you can start easy and level up later.
-
-## Backend included
-
-Essential server-side functionality comes built in — no extra setup required. At project creation you **choose your backend: Node.js or PHP** (Python is planned). Both expose the **same REST API** — same routing, `X-Api-Key` auth, CORS and rate limiting — so you can even switch later without rewriting your endpoints. See [docs/Backend.md](docs/Backend.md) for details.
-
-## Customizable, but with sensible defaults
-
-Nibula ships with a clean, opinionated layout so beginners are never lost. But it isn't a cage: as long as you follow a few small conventions and the defined paths, you're free to customize the subpaths of your **components, backend endpoints, and JS/SCSS modules** however you like.
-
-## Prerequisites
-
-### Required
-
-* **Node.js**: v18.0.0 or higher — **always required** (the Nibula CLI, the build, and the optional Node backend all run on Node)
-* **Composer**: **only required if you choose the PHP backend**, to install its PHP dependencies. If you pick the **Node** backend, Composer is never used — you can skip installing it entirely.
-### Recomended
-* *Suggested:* **Better Nunjucks** VS Code extension by Ed Heltzel
-* *Suggester:* **Material Icon Theme** VS Code extension by Philipp Kief
-
-## Installation
-
-Install the Nibula CLI once, globally:
-
-```
-npm install -g nibula
-```
-
-This gives you the `nib` command (Alternatives: `nbl`, `nibula`).
-
-## Create a project
-
-From the folder where you keep your websites, run:
-
-```
-nib new your-project
-```
-
-The scaffolder is interactive: you choose the **language** (JavaScript/TypeScript), the **CSS framework**, and the **backend** (Node.js or PHP). All dependencies are installed automatically — and if you pick **Node**, the PHP/Composer step is skipped, so you don't need Composer at all.
-
-Then start the dev server and visit `localhost:8080`:
-
-```
-cd your-project
-nib run
-```
-
-## Commands
-
-Run these from anywhere inside a project (except `nib new`, which you run wherever you want to create the project):
-
-| Command | Description |
-|---|---|
-| `nib new <name>` | Create your new project |
-| `nib run` | Start the dev server and build the output folder at runtime |
-| `nib cli` | Open the page-management assistant |
-| `nib build` | Build the output folder runtime |
-| `nib clean` | Remove the output directory |
-| `nib update` | Update the CLI to the latest version |
-
-Before scaffolding, nib new checks the npm registry for a newer version and offers to update first. If you accept, Nibula updates itself and then creates the project with the new version automatically — no need to re-run the command. If the registry is unreachable, the check is skipped and creation proceeds normally.
-
-## Managing pages
-
-Instead of creating and wiring up multiple files by hand, let the interactive assistant do it for you. To create, remove, or rename pages and configure the output path, run:
-
-```bash
-nib cli
-```
-
-See [docs/Assistant CLI.md](docs/Assistant%20CLI.md) for details.
-
-## Deploying
-
-Nibula builds a static site into your `out` folder, which you upload to a web
-server. Which backend you chose affects deployment:
-
-- **PHP** runs on ordinary shared hosting (Apache/IIS) or a VPS with PHP-FPM — no process to keep alive.
-- **Node** runs as a long-running service on a VPS; the web server reverse-proxies `/api` to it.
-
-The shipped `.htaccess`, `web.config` and `nginx.conf` cover **both** backends.
-See [docs/Deploy.md](docs/Deploy.md) for the full guide, including how to start
-the Node service on your server.
-
-## Roadmap
-
-* [ ] Add support for multiple themes
-* [x] Backend integration choice — pick **PHP or Node.js** at creation (Python planned)
-* [ ] Extend documentation with advanced usage examples
+# ✏️ Nibula
+
+[![Version](https://img.shields.io/npm/v/nibula?label=version&color=blue)](https://www.npmjs.com/package/nibula)
+[![License](https://img.shields.io/npm/l/nibula?color=blue)](LICENSE)
+![Eleventy](https://img.shields.io/badge/built%20on-11ty-black?logo=eleventy)
+
+**Nibula** is an open source static site generator built on top of [Eleventy](https://www.11ty.dev/), with one clear mission: make the jump from small hand-written practice sites to a real project setup as gentle as possible.
+
+If you've only ever written HTML, CSS, and a bit of JavaScript, moving to a "framework" usually feels like starting over: new syntax, new rules, new folder structures, and a pile of documentation before you can even see a page on screen. Nibula is designed to avoid exactly that. You keep working with the **three languages that matter — HTML, CSS, and JavaScript** — and the tool quietly handles the tedious parts around them. The goal is simple: even someone with little experience should always know *where to put their hands*.
+
+### ✨ Why choose Nibula?
+
+It's a great fit for **showcase and brochure-style websites** (portfolios, landing pages, small business sites), when you want something clean and fast without dragging in a framework that takes weeks to learn and handle.
+
+Building a website from scratch means putting together a lot of moving parts: SEO, dependency setup, deployment and server configuration, project structure. Nibula takes care of all of that for you, so you can focus on your content — while still picking up conventions and working habits that are common to the most widely used frameworks, Angular among them.
+
+### 📌 Other things worth knowing
+
+- 🔎 **SEO made simple** — managed from one central place; `sitemap`, `llms.txt`, and `robots.txt` are generated automatically
+- 🖱️ **A helpful CLI** — create a page with one command instead of hand-writing ten separate files
+- ⚙️ **Server configs handled for you** — `.htaccess` and `web.config` are generated automatically, and an `nginx.conf` is provided so that anyone comfortable with nginx already has what they need to run the site outside of shared hosting
+- 🎨 **Pick your CSS framework** — choose from 4 pre-installed options (or none), and switch later in a few guided steps
+- 🔌 **Pick your backend** — Node.js or PHP, chosen at creation (choose carefully, based on where you plan to publish)
+- 🧩 **Your own modules** — add your own SCSS and JS/TS modules freely and easily
+- 🪶 **Lightweight by default** — SCSS frameworks can be filtered so you ship only what you actually use
+
+### 🤔 When not to choose it?
+
+- **Heavily stateful interfaces** — dashboards, admin panels, editors, anything that keeps changing under the user's hands. A single-page application with React, Vue, or Angular is the right tool there.
+- **Pages generated at request time** — catalogues that depend on the logged-in user, personalised pricing, content that changes by the minute. Nibula builds pages beforehand, not during the visit.
+
+## ⚙️ Backend included
+
+Essential server-side functionality comes built in — no extra setup required. At project creation you **choose your backend: Node.js or PHP**. Both expose the **same REST API** — same routing, `X-Api-Key` auth, CORS and rate limiting — so you can even switch later without rewriting your endpoints. See [docs/Backend.md](docs/Backend.md) for details.
+
+## 🧭 Customizable, but with sensible defaults
+
+Nibula ships with a clean, opinionated layout so beginners are never lost. But it isn't a cage: as long as you follow a few small conventions and the defined paths, you're free to customize the subpaths of your **components, backend endpoints, and JS/SCSS modules** however you like.
+
+## 📋 Prerequisites
+
+### Required
+
+* **Node.js**: v18.0.0 or higher
+* **Composer** *(only if you choose the PHP backend)*: latest version
+
+### Recommended
+
+* **Better Nunjucks** — VS Code extension by **Ed Heltzel**
+* **Material Icon Theme** — VS Code extension by **Philipp Kief**
+
+## 📦 Installation
+
+Install Nibula once, globally:
+
+```
+npm install -g nibula
+```
+
+This gives you the `nib` command (alternatives: `nbl`, `nibula`).
+
+## 🚀 Create a project
+
+From the folder where you keep your websites, run:
+
+```
+nib new your-project
+```
+
+The scaffolder is interactive: you choose the **language** (JavaScript/TypeScript), the **CSS framework**, and the **backend** (Node.js or PHP). All dependencies are installed automatically — and if you pick **Node**, the PHP/Composer step is skipped, so you don't need Composer at all.
+
+Once the dependencies are installed, move into the project folder and start the dev server (`localhost:8080`):
+
+```
+cd your-project
+nib run
+```
+
+## 💻 Commands
+
+Run these from anywhere inside a project — except `nib new`, which must be run **outside** a project, in the folder where you want the new one created.
+
+| Command | Description |
+|---|---|
+| `nib new <name>` | Create your new project |
+| `nib run` | Start the dev server and build the output folder at runtime |
+| `nib cli` | Open the page-management assistant |
+| `nib build` | Build the output folder |
+| `nib clean` | Remove the output directory |
+| `nib update` | Update Nibula to the latest version (applies from your next project on) |
+
+## 📄 Managing pages
+
+Instead of creating and wiring up multiple files by hand, let the interactive assistant do it for you. To create, remove, or rename pages and configure the output path, run:
+
+```bash
+nib cli
+```
+
+See [docs/Assistant CLI.md](docs/Assistant%20CLI.md) for details.
+
+## 🌍 Deploying
+
+Nibula builds a static site into your `out` folder, which you upload to a web
+server. Which backend you chose affects deployment:
+
+- **Node** runs as a long-running service on a VPS; the web server reverse-proxies `/api` to it.
+- **PHP** runs on ordinary shared hosting (Apache/IIS) or a VPS with PHP-FPM — no process to keep alive.
+
+The shipped `.htaccess`, `web.config` and `nginx.conf` cover **both** backends.
+See [docs/Deploy.md](docs/Deploy.md) for the full guide, including how to start
+the Node service on your server.
+
+## 🙌 Wrapping up
+
+Thanks for giving Nibula a try.
+
+It's a one-person project, so every bit of feedback counts more than you'd think: if something breaks, if the documentation isn't clear, or if a feature is missing, open an [issue](https://github.com/Rhaastrake/Nibula/issues) — even just to tell me what you built with it.
+
+If Nibula was useful to you, leaving a ⭐ on the repository is the easiest way to help other people find it.