chore: initial commit

docs/usage.md

@@ -0,0 +1,119 @@
+# Usage
+
+Learn how to build and use Nixible configurations.
+
+## Using flakeModule
+
+The recommended way to use Nixible is with the flakeModule:
+
+```nix title="flake.nix"
+{
+  inputs = {
+    flake-parts.url = "github:hercules-ci/flake-parts";
+    nixible.url = "gitlab:TECHNOFAB/nixible?dir=lib";
+  };
+  
+  outputs = inputs@{ flake-parts, ... }:
+    flake-parts.lib.mkFlake { inherit inputs; } {
+      imports = [ nixible.flakeModule ];
+      systems = # ...
+
+      perSystem = { pkgs, ... }: {
+        nixible = {
+          deploy = {
+            dependencies = [ pkgs.rsync ];
+            inventory = {
+              webservers = {
+                hosts = {
+                  web1 = { ansible_host = "192.168.1.10"; };
+                };
+              };
+            };
+            playbook = [{
+              name = "Deploy application";
+              hosts = "webservers";
+              tasks = [{
+                name = "Deploy files";
+                copy = {
+                  src = "{{ pwd }}/dist/";
+                  dest = "/var/www/";
+                };
+              }];
+            }];
+          };
+        };
+      };
+    };
+    };
+  };
+}
+```
+
+Then run with:
+
+```bash
+nix run .#nixible:deploy
+
+# With ansible-playbook options
+nix run .#nixible:deploy -- --check --diff --limit web1
+```
+
+## Using the CLI directly
+
+You can also create CLI packages directly:
+
+```nix title="flake.nix"
+{
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";
+    nixible.url = "gitlab:TECHNOFAB/nixible?dir=lib";
+  };
+  
+  outputs = { nixpkgs, nixible, ... }: let
+    pkgs = nixpkgs.legacyPackages.x86_64-linux;
+    lib = nixpkgs.lib;
+    nixible_lib = nixible.lib { inherit pkgs lib; };
+  in {
+    packages.x86_64-linux.deploy = nixible_lib.mkNixibleCli ./deploy.nix;
+  };
+}
+```
+
+Then run with:
+
+```bash
+nix run .#deploy
+
+# Dry run with diff
+nix run .#deploy -- --check --diff
+
+# Limit to specific hosts
+nix run .#deploy -- --limit webservers
+
+# Extra variables
+nix run .#deploy -- --extra-vars "env=production debug=true"
+# etc.
+```
+
+## Variables
+
+Nixible automatically provides these variables to your playbooks:
+
+- `pwd`: Current working directory when nixible is run
+- `git_root`: Git repository root (empty if not in a git repo)
+
+Use them in your playbooks:
+
+```nix
+playbook = [{
+  name = "Deploy from current directory";
+  hosts = "localhost";
+  tasks = [{
+    name = "Copy files";
+    copy = {
+      src = "{{ pwd }}/dist/";
+      dest = "/var/www/";
+    };
+  }];
+}];
+```