docs: add commands example

examples/project-commands/Hello.avdl

@@ -0,0 +1,6 @@
+protocol Hello {
+    record Hello {
+        string message;
+        int timestamp;
+    }
+}

examples/project-commands/README.md

@@ -0,0 +1,42 @@
+# project-commands
+
+> **Warning**
+> If you copy the flake.nix remember to `git add [-N|--intent-to-add] flake.nix`, otherwise it won't work
+
+This example shows how to create scripts for your project, by leveraging [mission-control](https://github.com/Platonic-Systems/mission-control)
+
+This is a **potential** alternative to:
+
+- Using a `Makefile` to manage your project's scripts
+- Using the popular [Scripts To Rule Them All](https://github.com/github/scripts-to-rule-them-all) approach (having a `scripts/` folder)
+- Using a `bin/` folder
+
+## Explanation
+
+In this example we use the [avro-tools](https://avro.apache.org/) to convert our scripts from `.avdl` to `.avsc`.
+
+You don't need to know anything about avro to understand mission-control and use this example (that's nix baby 🚀).
+
+When setting up [mission-control](https://github.com/Platonic-Systems/mission-control), we add
+one script called `build`. Because of `wrapperName = "run";`, once we open the shell created by nix,
+the commands will be listed as `run build`.
+
+mission-control depends on flake-root, which also exposes the helpful `$FLAKE_ROOT` variable.
+
+After creating the scripts, we need to pass the newly created scripts to the desired shell, in this example we use the default shell.
+
+## Usage
+
+Run:
+
+```sh
+nix develop
+```
+
+And mission-control will print in the new shell the available commands (you should see only one).
+
+Try running
+
+```sh
+run build
+```

examples/project-commands/flake.lock

@@ -0,0 +1,95 @@
+{
+  "nodes": {
+    "flake-parts": {
+      "inputs": {
+        "nixpkgs-lib": "nixpkgs-lib"
+      },
+      "locked": {
+        "lastModified": 1685662779,
+        "narHash": "sha256-cKDDciXGpMEjP1n6HlzKinN0H+oLmNpgeCTzYnsA2po=",
+        "owner": "hercules-ci",
+        "repo": "flake-parts",
+        "rev": "71fb97f0d875fd4de4994dfb849f2c75e17eb6c3",
+        "type": "github"
+      },
+      "original": {
+        "id": "flake-parts",
+        "type": "indirect"
+      }
+    },
+    "flake-root": {
+      "locked": {
+        "lastModified": 1680964220,
+        "narHash": "sha256-dIdTYcf+KW9a4pKHsEbddvLVSfR1yiAJynzg2x0nfWg=",
+        "owner": "srid",
+        "repo": "flake-root",
+        "rev": "f1c0b93d05bdbea6c011136ba1a135c80c5b326c",
+        "type": "github"
+      },
+      "original": {
+        "owner": "srid",
+        "repo": "flake-root",
+        "type": "github"
+      }
+    },
+    "mission-control": {
+      "locked": {
+        "lastModified": 1683658484,
+        "narHash": "sha256-JkGnWyYZxOnyOhztrxLSqaod6+O/3rRypq0dAqA/zn0=",
+        "owner": "Platonic-Systems",
+        "repo": "mission-control",
+        "rev": "a0c93bd764a3c25e6999397e9f5f119c1b124e38",
+        "type": "github"
+      },
+      "original": {
+        "owner": "Platonic-Systems",
+        "repo": "mission-control",
+        "type": "github"
+      }
+    },
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 1687502512,
+        "narHash": "sha256-dBL/01TayOSZYxtY4cMXuNCBk8UMLoqRZA+94xiFpJA=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "3ae20aa58a6c0d1ca95c9b11f59a2d12eebc511f",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "ref": "nixos-unstable",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "nixpkgs-lib": {
+      "locked": {
+        "dir": "lib",
+        "lastModified": 1685564631,
+        "narHash": "sha256-8ywr3AkblY4++3lIVxmrWZFzac7+f32ZEhH/A8pNscI=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "4f53efe34b3a8877ac923b9350c874e3dcd5dc0a",
+        "type": "github"
+      },
+      "original": {
+        "dir": "lib",
+        "owner": "NixOS",
+        "ref": "nixos-unstable",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "root": {
+      "inputs": {
+        "flake-parts": "flake-parts",
+        "flake-root": "flake-root",
+        "mission-control": "mission-control",
+        "nixpkgs": "nixpkgs"
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}

examples/project-commands/flake.nix

@@ -0,0 +1,37 @@
+{
+  description = "Description for the project";
+
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+
+    mission-control.url = "github:Platonic-Systems/mission-control";
+    flake-root.url = "github:srid/flake-root";
+  };
+
+  outputs = inputs@{ flake-parts, ... }:
+    flake-parts.lib.mkFlake { inherit inputs; } {
+      imports = [
+        inputs.mission-control.flakeModule
+        inputs.flake-root.flakeModule
+      ];
+      systems = [ "x86_64-linux" "aarch64-darwin" "x86_64-darwin" ];
+      perSystem = { config, self', inputs', pkgs, system, ... }: {
+        devShells.default = pkgs.mkShell {
+          nativeBuildInputs = with pkgs; [ avro-tools ];
+          inputsFrom = [ config.mission-control.devShell config.flake-root.devShell ];
+        };
+        mission-control = {
+          wrapperName = "run";
+          scripts = {
+            build = {
+              description = "convert files from .avdl to .avsc";
+              exec = ''
+                avro-tools idl2schemata "$FLAKE_ROOT/Hello.avdl" .
+              '';
+              category = "Development";
+            };
+          };
+        };
+      };
+    };
+}

examples/shell-environments/README.md

@@ -1,5 +1,8 @@
 # shell-environment
 
+> **Warning**
+> If you copy the flake.nix remember to `git add [-N|--intent-to-add] flake.nix`, otherwise it won't work
+
 This example shows how to create a shell environment which
 includes a diverse set of tools:
 
@@ -14,9 +17,6 @@ You can search for more package in [nix packages](https://search.nixos.org/packa
 
 ## Usage
 
-> **Warning**
-> If you copy the flake.nix remember to add it to git, otherwise it won't work
-
 The [`devShells` option](https://flake.parts/options/flake-parts.html#opt-perSystem.devShells) is used by the following command:
 
 ```sh