Added a part explaining what is meant by literate, explained about the README.org en advised a workflow

henrovnix/README.org

@@ -51,6 +51,278 @@ The system provides a predefined baseline configuration that installs and enable
 
 Core packages are installed as part of the base configuration. Additional software can be incorporated in a controlled and modular manner by extending configuration files.
 
+* what you don't get
+
+This is by no means a complete or bug-free environment. Certain components — such as the XDG portals — may still behave unpredictably or require additional tweaking. The goal is to provide a solid starting point for those who want to learn how to build an iterative system from a minimal foundation. Consider it a base to extend, refine, and improve over time. This project is very much a work in progress.
+
+** What Is a Literate System in the Context of NixOS?
+
+A literate system combines documentation and implementation into a single, coherent source.
+In this repository, that source is:
+
+#+begin_src bash :tangle no block
+README.org
+#+end_src
+
+Everything originates from this file:
+
+- Architectural explanations
+- Design decisions
+- NixOS modules
+- Home-Manager modules
+- Generated documentation
+
+There is no separation between “docs” and “code”.
+The documentation explains the intent.
+The source blocks define the system.
+Org-mode turns that narrative into both executable configuration and readable documentation.
+
+The README is not describing the system.
+The README *is* the system.
+
+---
+
+** Two Types of Code Blocks
+
+This literate system uses two different kinds of source blocks.
+
+**1. Documentation Blocks**
+
+These blocks exist purely for documentation purposes.
+They generate visible code blocks in the exported documentation, but they do not create files.
+
+Example:
+
+#+begin_src bash :tangle no
+<tekst>
+#+end_src
+
+These are used to show commands, examples, or explanatory snippets in the generated documentation.
+
+They are never tangled into the filesystem.
+
+---
+
+**2. File-Generating Blocks**
+
+These blocks generate real `.nix` files and insert the same code into the documentation.
+
+Example structure:
+
+** =install_packages.nix=
+
+<tekst>
+
+#+begin_src nix :tangle configuration/apps/install_packages.nix :noweb tangle :mkdirp yes
+<tekst>
+#+end_src
+
+Explanation:
+
+- The headline `=install_packages.nix=` becomes a documentation chapter.
+- The paragraph `<tekst>` explains what the module does.
+- The source block generates the file:
+
+  configuration/apps/install_packages.nix
+
+- The same source block is rendered as a code block in the documentation.
+
+This means:
+
+- The explanation and the implementation live side-by-side.
+- The documentation cannot drift away from the code.
+- The generated `.nix` file is always derived from the canonical explanation.
+
+---
+
+** The Two Core Commands
+
+There are exactly two commands that matter.
+
+**1. Generate all `.nix` files**
+
+#+begin_src bash :tangle no block
+emacs README.org --batch -f org-babel-tangle
+#+end_src
+
+This command:
+
+- Regenerates `./configuration`
+- Regenerates `./home`
+- Overwrites previously generated modules
+- Ensures the system matches the README
+
+---
+
+**2. Generate documentation**
+
+#+begin_src bash :tangle no block
+emacs --batch -l org -l ox-html README.org -f org-html-export-to-html --kill
+#+end_src
+
+This command exports the same README into HTML documentation.
+
+---
+
+In practice you usually combine them:
+
+#+begin_src bash :tangle no block
+emacs README.org --batch -f org-babel-tangle && emacs --batch -l org -l ox-html README.org -f org-html-export-to-html --kill
+#+end_src
+
+First the system is generated.
+Then the documentation is generated.
+Both come from the same source.
+
+---
+
+** Editing Generated Files
+
+The directories:
+
+- `./configuration`
+- `./home`
+
+are fully generated by:
+
+#+begin_src bash :tangle no block
+emacs README.org --batch -f org-babel-tangle
+#+end_src
+
+Editing these files directly is allowed only temporarily, for experimentation or testing.
+
+Structural or permanent changes must always be implemented in the corresponding section inside `README.org`.
+
+If you change a file in `./configuration` or `./home` without updating the README, your changes will disappear on the next tangle.
+
+Generated directories are output, not source.
+
+---
+
+** Recommended Workflow
+
+This workflow allows safe experimentation while preserving literate structure.
+
+1. Change any existing file in `./assets`, `./home` or `./configuration`
+2. Commit your experimental change
+3. Test the configuration
+4. If satisfied, migrate the change into `README.org`
+5. Regenerate system and documentation
+6. Commit again
+7. Test again
+
+Commands:
+
+#+begin_src bash :tangle no block
+git add .
+git commit -m "experiment: local change"
+
+sudo nixos-rebuild test --flake .#your_hostname
+#+end_src
+
+After confirming the change:
+
+#+begin_src bash :tangle no block
+emacs README.org --batch -f org-babel-tangle && emacs --batch -l org -l ox-html README.org -f org-html-export-to-html --kill
+
+git add .
+git commit -m "literate: structural update"
+
+sudo nixos-rebuild test --flake .#your_hostname
+#+end_src
+
+If you are confident about your changes, you may skip steps 1–3 and edit `README.org` directly.
+
+---
+
+** Folder Structure Explained
+
+The repository separates generated system code from non-generated supporting files.
+
+****./assets**
+
+Contains non-generated assisting files such as:
+
+- Icons
+- Themes
+- Static configuration files
+
+These files are safe to edit directly.
+
+---
+
+***./assets/configuration**
+
+Contains non-generated assisting configuration files that influence several aspects of builds.
+
+Users are expected to modify these when needed.
+
+---
+
+***./configuration**
+
+Fully (re)generated by `README.org`.
+
+Contains:
+
+- All NixOS modules
+- Service definitions
+- System-level configuration
+
+This directory is output.
+
+---
+
+***./hardware**
+
+Contains non-generated `hardware.nix` files detailing hardware-specific details.
+
+This directory will likely be deprecated in the future.
+
+---
+
+***./home**
+
+Fully (re)generated by `README.org`.
+
+Contains:
+
+- All Home-Manager modules
+- User-level configuration
+- Shell and desktop configuration
+
+This directory is generated output.
+
+---
+
+***./machines**
+
+Contains one folder per machine you want to configure.
+
+Each machine folder contains non-generated files detailing specifics for that machine:
+
+- Host-specific overrides
+- Hardware references
+- Host definitions
+
+These determine how shared modules apply to each system.
+
+---
+
+** Final Principle
+
+A literate NixOS system guarantees:
+
+- Single source of truth
+- No divergence between documentation and configuration
+- Reproducible system builds
+- Clear architectural reasoning
+- Controlled experimentation
+
+You are not maintaining configuration files.
+
+You are maintaining a structured narrative that builds an operating system.
+
 ** Base packages
 The baseline package set is defined explicitly within the repository to ensure reproducibility:
 
@@ -137,7 +409,7 @@ Available Flatpak identifiers can be discovered using:
 flatpak search <application-name>
 #+end_src
 
-or by browsing: https://flathub.org/.
+or by browsing: https://flathub.org/.(manually)
 
 The behavior and integration of Flatpak installation within the system are defined in =install_flatpaks.nix=, which reads the corresponding configuration files and ensures declarative installation.