docs: add Configuration page

doc/src/SUMMARY.md

@@ -10,6 +10,7 @@
     - [Develop](om/develop.md)
     - [CI](om/ci.md)
     - [Init](om/init.md)
+- [Configuration](./config.md)
 
 # Meta
 

doc/src/config.md

@@ -0,0 +1,6 @@
+# Omnix Configuration
+
+You can configure Omnix's behaviour on your repository by creating a top-level `om.yaml` file.  If there is no `om.yaml` file, Omnix will evaluate the flake's `.#om` output instead. Prefer creating a `om.yaml` in general, as it is faster to read than evaluating complex Nix flakes.
+
+> [!NOTE]
+> For am example `om.yaml`, see [that of omnix itself](https://github.com/juspay/omnix/blob/main/om.yaml)

doc/src/om/ci.md

@@ -66,7 +66,7 @@ Here's a more advanced example that configures a job matrix. This is useful when
 The `om ci gh-matrix` command outputs the matrix JSON for creating [a matrix of job variations](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/running-variations-of-jobs-in-a-workflow). An example configuration, using self-hosted runners, is shown below.
 
 > [!NOTE]
-> This currently requires an explicit CI configuration in your flake, viz.: `om.ci.default.root.dir = ".";`.
+> This currently requires an explicit [CI configuration](../config.md) in your flake, setting `om.ci.default.root.dir` to `.`.
 
 ```yaml
 # Run on aarch64-linux and aarch64-darwin
@@ -98,7 +98,7 @@ jobs:
 
 ## Configuring {#config}
 
-By default, `om ci` will build the top-level flake, but you can tell it to build sub-flakes (here, `./dir1` and `./dir2`) by adding the following output to your top-level flake:
+By default, `om ci` will build the top-level flake, but you can tell it to build sub-flakes (here, `./dir1` and `./dir2`) by adding the following to your [Om configuration](../config.md):
 
 ```nix
 # myproject/flake.nix

doc/src/om/develop.md

@@ -1,43 +1,51 @@
 # Develop
 
-The `om develop` should be used indirectly in direnv, via the `use omnix` directive in your `.envrc`:
+The `om develop` command should be used indirectly in direnv, via the `use omnix` directive in your `.envrc`.
 
-```sh
-source_url https://raw.githubusercontent.com/juspay/omnix/75ed48923835963e2f18baba08f54a8adc307ba2/omnixrc "sha256-8C2Jb5bHx/0cvm1+9gOlBEdWzbikCWT5UsJWewUAFt4="
+## Getting started {#start}
 
-use omnix
-```
+1. Put this in your `.envrc` file:
 
-`use omnix` wraps `use flake` (of nix-direnv) providing additional capabilities:
+    ```sh
+    source_url https://raw.githubusercontent.com/juspay/omnix/75ed48923835963e2f18baba08f54a8adc307ba2/omnixrc "sha256-8C2Jb5bHx/0cvm1+9gOlBEdWzbikCWT5UsJWewUAFt4="
 
-- Run [`om health`](health.md) to check the health of the Nix environment.
-- Run `cachix use` automatically if the project uses cachix.
-- Print a welcome text after spawning the Nix devshell.
+    use omnix
+    ```
+
+2. You should also create an empty (or fleshed out) [`om.yaml`](../config.md) file in your project to avoid Nix evaluation:
+
+    ```sh
+    touch om.yaml
+    ```
 
-The ideal goal here being that switching to a project should do everything necessary to get you started immediately.
 
-## `om.yaml`
+## What does it do? {#what}
 
-You should also create a `om.yaml` (empty file if there's no configuration) so your flake is not evaluated during direnv.
+`use omnix` wraps `use flake` (of [nix-direnv](https://nixos.asia/en/direnv)) providing additional capabilities:
+
+- Run [`om health`](health.md) to check the health of the Nix environment.
+  - Run `cachix use` automatically if the project uses cachix.
+- Print a welcome text after spawning the Nix devshell.
+
+The ideal goal here being that `cd`'ing to a project should do everything necessary to get you started immediately.
 
 ## Welcome text {#welcome}
 
-The welcome text can be configured in your om configuration:
+The welcome text can be configured in your [`om.yaml`](../config.md) file. For example:
 
-```nix
-{
-  om.develop.default = {
-    readme = ''
-      Welcome to our **project**
+```yaml
+develop:
+  default:
+    readme: |
+      🍾 Welcome to the **omnix** project
 
-      To get started, run the following:
+      To run omnix,
 
-      ```sh
-      just run
+      ```sh-session
+      just watch <args>
       ```
 
-      For more, read the README.md
-    '';
-  }
-}
+      (Now, as you edit the Rust sources, the above will reload!)
+
+      🍎🍎 Run 'just' to see more commands. See <https://nixos.asia/en/vscode> for IDE setup.
 ```

doc/src/om/health.md

@@ -39,19 +39,16 @@ To run use the health check configuration specified in a project flake, pass tha
 om health github:nammayatri/nammayatri
 ```
 
-## Configuring in `flake.nix` {#conf}
+## Per-project configuration {#conf}
 
-To add project specific health checks or configure health checks, add the following flake output:
+To add project specific health checks or configure health checks, add the following to your [`om.yaml`](../config.md):
 
-```nix
-{
-  outputs = inputs: {
-    om.health.default = {
-      # Add configuration here
-      caches.required = [ "https://ourproject.cachix.org" ];
-    };
-  };
-}
+```yaml
+health:
+  default:
+    caches:
+      required:
+        - "https://ourproject.cachix.org"
 ```
 
 To see all available configuration options, run `om health --dump-schema`. This will dump the schema of the configuration in JSON format. Convert that to a Nix attrset to see what can be added under the `om.health.default` attrset of your flake.
@@ -88,42 +85,4 @@ This will output:
 
 ### Adding devShell check {#devshell}
 
-> [!WARNING]
-> This section needs to be finalized for omnix. See [here](https://github.com/srid/haskell-template/pull/139/files) for the up-to-date proof of concept.
-
-You can automatically run `om health` whenever your Nix dev shell starts. To do this, import the flake module in your flake and use it in your devShell:
-
-```nix
-{
-  inputs = {
-    omnix-flake.url = "github:juspay/omnix?dir=nix/om";
-  };
-  outputs = inputs:
-    inputs.flake-parts.lib.mkFlake { inherit inputs; } {
-      imports = [
-        inputs.omnix-flake.flakeModules.default
-      ];
-      perSystem = { config, pkgs, ... }: {
-        devShells.default = pkgs.mkShell {
-          inputsFrom = [
-            config.om.health.outputs.devShell
-          ]
-        };
-      };
-    };
-}
-```
-
-Now suppose you have Nix 2.18 installed, but your project requires 2.19 or above due to the following config in its `flake.nix`:
-
-```nix
-flake.om.health.default = {
-  nix-version.min-required = "2.19.0";
-};
-```
-
-you can expect the devShell to print a giant message like this:
-
-<img width="501" alt="image" src="https://github.com/juspay/nix-health/assets/3998/9f3b3141-611f-484f-b897-3e375c02dff5">
-
-Note that you will still be dropped into the Nix dev shell (there's no way to abrupt the launching of a dev Shell).
+You can automatically run `om health` as part of direnv invocation; see [`om develop`](develop.md) for details.

doc/src/om/init.md

@@ -43,7 +43,7 @@ If there are multiple templates in the flake (as is the case with the builtin re
 
 ## Configuration spec {#spec}
 
-Omnix templates can be defined by adding a `om.template` flake output. This should be an attrset of templates. The value should contain the keys `template` (referring to original flake template) as well as `params`, defined as follows:
+Omnix templates can be defined by adding a `om.template` flake output [configuration](../config.md). This should be an attrset of templates. The value should contain the keys `template` (referring to original flake template) as well as `params`, defined as follows:
 
 There are two kinds of params. **String params** are defined as follows:
 
@@ -74,7 +74,7 @@ Both parameter types are distinguished by the presence of the relevant keys (`pl
 
 ## Testing templates {#test}
 
-The configuration can also include a `tests` key that defines a list of tests to run on the template. Each test is an attrset with `params` and `asserts` keys that indicates the parameter values to test along with the path existance assertions. [For example](https://github.com/juspay/nixos-unified-template/blob/3c4428ac94a4582a33e6fb3fe18df27bbc1e9eb7/modules/flake-parts/template.nix#L139-L157):
+The [configuration](../config.md) can also include a `tests` key that defines a list of tests to run on the template. Each test is an attrset with `params` and `asserts` keys that indicates the parameter values to test along with the path existance assertions. [For example](https://github.com/juspay/nixos-unified-template/blob/3c4428ac94a4582a33e6fb3fe18df27bbc1e9eb7/modules/flake-parts/template.nix#L139-L157):
 
 ```nix
 {