Converge on the org flake standard

.gitignore

@@ -2,5 +2,9 @@
 result
 result-*
 
+# devenv
+.devenv*
+devenv.local.nix
+
 # `mkdocs build` output, if you ever run mkdocs outside Nix
 documentation/site/

.vscode/extensions.json

@@ -0,0 +1,3 @@
+{
+  "recommendations": ["jnoortheen.nix-ide"]
+}

.vscode/settings.json

@@ -0,0 +1,25 @@
+{
+  "nix.enableLanguageServer": true,
+  "nix.serverPath": "nixd",
+  "nix.serverSettings": {
+    "nixd": {
+      "nixpkgs": {
+        "expr": "import (builtins.getFlake (builtins.toString ./.)).inputs.nixpkgs { }"
+      },
+      "formatting": {
+        "command": ["alejandra", "--quiet"]
+      },
+      "options": {
+        "flake-parts": {
+          "expr": "(builtins.getFlake (builtins.toString ./.)).debug.options"
+        },
+        "flake-parts-perSystem": {
+          "expr": "(builtins.getFlake (builtins.toString ./.)).currentSystem.options"
+        },
+        "nixos": {
+          "expr": "((builtins.getFlake (builtins.toString ./.)).inputs.nixpkgs.lib.nixosSystem { modules = [ { nixpkgs.hostPlatform = builtins.currentSystem; } ]; }).options"
+        }
+      }
+    }
+  }
+}

AGENTS.md

@@ -0,0 +1,27 @@
+# AGENTS.md
+
+MkDocs docs site + reveal.js slide deck tooling for external-systems
+flakes. Consumers import `flakeModules.default` (docs + slides) or
+`flakeModules.slides`, or call `lib.mkSlides`; `templates.default` is
+this whole repo. The reveal.js pin travels with those exports. This repo
+builds its own docs and deck with the same module.
+
+## Layout
+- `flake.nix`: consumer-facing inputs (org-pkgs; mkdocs-flake, reveal-js) and exports (lib, flakeModules), plus the dev partition wiring.
+- `lib/default.nix`: `mkSlides`. `flakeModules/slides.nix`: the `presenting.slides.*` module.
+- `flake-parts/`: consumer-facing modules, auto-imported (import-tree): `template.nix`. `flake-parts/scripts/inline-markdown.py` is used by `mkSlides`.
+- `dev/flake.nix` + `dev/flake.lock`: dev-only inputs. `dev/flake-module.nix`: the dev partition (formatter, checks, this repo's docs and deck).
+- `devenv.yaml` + `devenv.lock` + `devenv.nix`: the dev shell. The org shell comes from external-systems/pkgs (`org-pkgs/devenv` in devenv.yaml).
+- `documentation/`: `flake-module.nix`, MkDocs site (`mkdocs.yml`, `docs/`) and reveal.js deck (`slides/`).
+
+## Tool loop
+- The shell is devenv. If `DEVENV_ROOT` is unset, run commands with `devenv shell -- <cmd>`.
+- `git add` new files before any `nix` command.
+- `fmt`, then `check`. Both must pass before a change is done.
+- After `nix flake update org-pkgs`, run `sync-locks` in the same commit.
+
+## Rules
+- Load the `nix-style` skill before editing any `.nix` file, and `mkdocs-reveal` before changing the exports.
+- Dev-only inputs go in `dev/flake.nix`, never `flake.nix`.
+- Never change the shape of `lib`, `flakeModules` or `templates` without updating every consumer (pkgs template, skills, secrets, not-secrets, modules, home, clanServices).
+- Work on a branch and open a PR. Never push to `main`.

README.md

@@ -12,15 +12,17 @@ reveal.js + MkDocs, built by a Nix flake. Two ways to use it:
 A static documentation website ([MkDocs](https://www.mkdocs.org) +
 [Material](https://squidfunk.github.io/mkdocs-material/)) and a slide deck
 ([reveal.js](https://revealjs.com)), both built by a Nix flake. No Python,
-Node or npm to install, only Nix.
+Node or npm to install, only Nix (and devenv for the dev shell).
 
 ```bash
-nix run .#watch-documentation   # live docs preview   → http://127.0.0.1:8000
-nix run .#serve-slides          # live slides preview → http://127.0.0.1:8000
+devenv allow                    # auto-activates the shell on cd (after `devenv hook`)
+fmt                             # nix fmt: treefmt with the org linters
+check                           # nix flake check: lint, lock sync, both builds
+docs-build                      # static docs to ./result-docs; open index.html from disk
+devenv up                       # live docs on :8981 and slides on :8982
 
 nix build .#documentation       # ./result = docs website
 nix build .#slides              # ./result = slide deck
-nix flake check                 # build both + lint the Nix code
 ```
 
 Remember to `git add` new files: Nix only sees files git tracks.
@@ -65,11 +67,16 @@ present — the embed via `documentation.mkdocs-preBuildHook`
 call the builder directly: `inputs.presenting.lib.mkSlides { inherit pkgs; slidesDir = ./slides; }`.
 
 ```text
-flake.nix          inputs + exports (lib, flakeModules, template), locked in flake.lock
+flake.nix          inputs (follow external-systems/pkgs) + exports (lib, flakeModules, template)
 lib/               mkSlides: the root-agnostic deck builder other flakes reuse
 flakeModules/      the exportable flake-parts module (presenting.slides.* options)
-flake-parts/       this repo's own config, auto-imported: docs settings, checks
+flake-parts/       consumer-facing modules, auto-imported: the template output
+dev/               dev partition: inputs (dev/flake.lock), formatter, checks, docs
+devenv.yaml        dev shell (devenv CLI), the org shell from external-systems/pkgs
+documentation/     flake-module.nix + MkDocs site (mkdocs.yml, docs/) + slides/ deck
 .github/workflows/ pages.yml: check, build and deploy the docs site to GitHub Pages
-documentation/     MkDocs site: mkdocs.yml + docs/*.md
-slides/            reveal.js deck: index.html + slides.md
+.vscode/           nixd (Nix language server) settings
 ```
+
+The repo follows the org flake standard (nix-style skill): after
+`nix flake update org-pkgs`, run `sync-locks` in the same commit.

dev/flake-module.nix

@@ -0,0 +1,9 @@
+# Dev partition: the org base (treefmt, lock-sync, docs and slides as
+# checks) from pkgs, and this repo's own docs site and deck. A consumer
+# of lib, flakeModules or templates never evaluates it.
+{inputs, ...}: {
+  imports = [
+    inputs.org-pkgs.flakeModules.dev
+    ../documentation/flake-module.nix
+  ];
+}

dev/flake.nix

@@ -0,0 +1,18 @@
+{
+  description = "Development-only inputs for presenting (the dev partition)";
+
+  # Locked in dev/flake.lock, never in the main flake.lock. dev-nixpkgs
+  # must lock the same rev as the root nixpkgs (checks.lock-sync; fix
+  # with `sync-locks`). No `presenting` input: this repo's docs use its
+  # own flakeModules (documentation/flake-module.nix).
+  inputs = {
+    dev-nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+
+    treefmt-nix = {
+      url = "github:numtide/treefmt-nix";
+      inputs.nixpkgs.follows = "dev-nixpkgs";
+    };
+  };
+
+  outputs = _: {};
+}

devenv.lock

@@ -0,0 +1,106 @@
+{
+  "nodes": {
+    "devenv": {
+      "locked": {
+        "dir": "src/modules",
+        "lastModified": 1793199252,
+        "narHash": "sha256-LRgdAdMHL3uIX+kix/oyMzG+gMxzSYOzLrrRaoZthog=",
+        "owner": "cachix",
+        "repo": "devenv",
+        "rev": "0d6c556e5f862c14a75a543e2ee4fdb7acc005ad",
+        "type": "github"
+      },
+      "original": {
+        "dir": "src/modules",
+        "owner": "cachix",
+        "repo": "devenv",
+        "type": "github"
+      }
+    },
+    "flake-parts": {
+      "inputs": {
+        "nixpkgs-lib": [
+          "org-pkgs",
+          "nixpkgs"
+        ]
+      },
+      "locked": {
+        "lastModified": 1790898470,
+        "narHash": "sha256-zTwuwezD0w3hpga6a6P8emidzAZFyWqlNeRBlpWOOl8=",
+        "owner": "hercules-ci",
+        "repo": "flake-parts",
+        "rev": "024633cd702b10285db5cb19b40ad48d2399ba60",
+        "type": "github"
+      },
+      "original": {
+        "owner": "hercules-ci",
+        "repo": "flake-parts",
+        "type": "github"
+      }
+    },
+    "import-tree": {
+      "locked": {
+        "lastModified": 1788467110,
+        "narHash": "sha256-ljEMTXP/rH0tOvDzc9gzwww6KcHRPRnEHzd9lK48V7s=",
+        "owner": "denful",
+        "repo": "import-tree",
+        "rev": "eb1b52eaecc57f7c136d07ae8a93e724dfecac46",
+        "type": "github"
+      },
+      "original": {
+        "owner": "denful",
+        "repo": "import-tree",
+        "type": "github"
+      }
+    },
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 1793110635,
+        "narHash": "sha256-dhoW6VgFWlaodSY5jrBn+CF2FLmaUvDVgM7+C7T2+NM=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "31ecbaca1bdefa45dffc409f0250bd8039ea0010",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "ref": "nixos-unstable",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "org-pkgs": {
+      "inputs": {
+        "flake-parts": "flake-parts",
+        "import-tree": "import-tree",
+        "nixpkgs": "nixpkgs"
+      },
+      "locked": {
+        "lastModified": 1793444658,
+        "narHash": "sha256-Fk+uJAmFS0FbZqH48EoqRifwiJM1Z1TlfX5f4hZS4/M=",
+        "owner": "external-systems",
+        "repo": "pkgs",
+        "rev": "e058d99fe9f04de4fc47ce892d0efbfebba7929b",
+        "type": "github"
+      },
+      "original": {
+        "owner": "external-systems",
+        "repo": "pkgs",
+        "rev": "e058d99fe9f04de4fc47ce892d0efbfebba7929b",
+        "type": "github"
+      }
+    },
+    "root": {
+      "inputs": {
+        "devenv": "devenv",
+        "nixpkgs": [
+          "org-pkgs",
+          "nixpkgs"
+        ],
+        "org-pkgs": "org-pkgs"
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}

devenv.nix

@@ -0,0 +1,3 @@
+# presenting's additions to the org shell (org-pkgs/devenv): none yet.
+# Languages, services and app processes go here.
+_: {}

devenv.yaml

@@ -0,0 +1,15 @@
+# devenv CLI entry: devenv shell, auto-activation (devenv hook + devenv
+# allow), devenv up, devenv test, devenv mcp. nixpkgs comes from pkgs at
+# the rev flake.lock holds (checks.lock-sync; fix with `sync-locks`).
+# The input is NOT named `pkgs`: devenv passes every input to devenv.nix
+# as a module argument, so an input called `pkgs` would replace nixpkgs'
+# pkgs ("attribute 'bash' missing").
+inputs:
+  org-pkgs:
+    url: github:external-systems/pkgs/e058d99fe9f04de4fc47ce892d0efbfebba7929b
+  nixpkgs:
+    follows: org-pkgs/nixpkgs
+imports:
+  # The org shell: fmt, check, sync-locks, docs, slides; devenv up serves
+  # docs and slides.
+  - org-pkgs/devenv

documentation/docs/getting-started.md

@@ -44,12 +44,13 @@ Each command starts a small web server. Leave it running, edit files, and
 refresh the browser.
 
 ```bash
-nix run .#watch-documentation   # docs   → http://127.0.0.1:8000 (auto-reloads)
-nix run .#serve-slides          # slides → http://127.0.0.1:8000 (refresh by hand)
+nix run .#watch-documentation   # docs   → http://127.0.0.1:8981 (auto-reloads)
+nix run .#serve-slides -- 8982  # slides → http://127.0.0.1:8982 (refresh by hand)
 ```
 
-Both use port 8000, so run one at a time, or give the slides another
-port: `nix run .#serve-slides -- 8001`.
+Or run both at once in the devenv shell: `devenv up`. The docs port is
+`dev_addr` in `documentation/mkdocs.yml`; the slides take the port as an
+argument (default 8000).
 
 The first run downloads and builds the tools, which takes a few minutes.
 Later runs start in seconds.
@@ -73,8 +74,8 @@ nix build .#documentation .#slides
 ## 5. Check everything before you push
 
 ```bash
-nix fmt .           # format the .nix files
-nix flake check     # builds both sites and lints the Nix code
+nix fmt             # format and lint (treefmt)
+nix flake check     # builds both sites, lints, checks the lock files
 ```
 
 ## 6. Publish to GitHub Pages

documentation/docs/index.md

@@ -5,7 +5,7 @@ This repository builds **two static websites** from plain text files:
 | What | Source | Built with | Build command |
 | --- | --- | --- | --- |
 | This documentation site | `documentation/` | [MkDocs](https://www.mkdocs.org) + [Material](https://squidfunk.github.io/mkdocs-material/) | `nix build .#documentation` |
-| A slide deck | `slides/` | [reveal.js](https://revealjs.com) | `nix build .#slides` |
+| A slide deck | `documentation/slides/` | [reveal.js](https://revealjs.com) | `nix build .#slides` |
 
 Both builds produce a folder of HTML, CSS and JavaScript (`./result`) that
 any static host can serve: GitHub Pages, Cloudflare Pages, Netlify, an S3