feat: update documentation, lib functions, modules, and packages

docs/templates.md

@@ -0,0 +1,162 @@
+# Templates
+
+Boilerplate templates for quickly adding new packages or modules to m3ta-nixpkgs.
+
+## Available Templates
+
+| Template | Command | Creates |
+|---------|---------|---------|
+| Package | `nix flake init -t .#package` | `templates/package/` |
+| NixOS Module | `nix flake init -t .#nixos-module` | `templates/nixos-module/` |
+| Home Manager Module | `nix flake init -t .#home-manager-module` | `templates/home-manager-module/` |
+
+## Using Templates
+
+### 1. List Available Templates
+
+```bash
+nix flake show --templates .
+```
+
+### 2. Initialize from a Template
+
+```bash
+# Package
+nix flake init -t .#package
+
+# NixOS Module
+nix flake init -t .#nixos-module
+
+# Home Manager Module
+nix flake init -t .#home-manager-module
+```
+
+Note: `nix flake init` copies the template contents into the current directory. Use a subdirectory name:
+
+```bash
+mkdir new-package && cd new-package
+nix flake init -t ..#package
+```
+
+## Package Template
+
+Creates a complete package structure:
+
+```
+templates/package/
+├── default.nix    # Package definition with comments
+```
+
+### Fields to Fill In
+
+| Field | Location | Notes |
+|-------|----------|-------|
+| `pname` | `default.nix` | Package name (kebab-case) |
+| `version` | `default.nix` | Semantic version |
+| `src` | `default.nix` | Fetcher (GitHub, URL, Git, etc.) |
+| `hash` | `default.nix` | Use `lib.fakeHash`, build to get real hash |
+| `meta.description` | `default.nix` | Short one-line description |
+| `meta.homepage` | `default.nix` | Project URL |
+| `meta.license` | `default.nix` | Use `lib.licenses.*` |
+| `meta.platforms` | `default.nix` | Usually `platforms.linux` |
+| `meta.mainProgram` | `default.nix` | Main binary name |
+
+### Common Build Systems
+
+```nix
+# Rust (recommended)
+rustPlatform.buildRustPackage rec { ... }
+
+# Python
+python3.pkgs.buildPythonPackage rec { ... }
+
+# Node.js
+pkg-config, nodejs, npm2nix, or pnpm + prisma
+
+# Shell script
+writeShellScriptBin "name" ''echo hello''
+
+# Go
+go mdbook build
+
+# Generic C/Make
+stdenv.mkDerivation { ... }
+```
+
+See [Adding Packages](./guides/adding-packages.md) for detailed instructions.
+
+## NixOS Module Template
+
+Creates a complete NixOS module:
+
+```
+templates/nixos-module/
+├── default.nix    # Module with options
+└── README.md       # Module documentation
+```
+
+### Fields to Fill In
+
+| Field | Location | Notes |
+|-------|----------|-------|
+| Module name | `default.nix` | File name matches `m3ta.<name>` |
+| Options | `default.nix` | Add under `options.m3ta.<name>` |
+| Config | `default.nix` | Add under `config.m3ta.<name>` |
+| Description | `README.md` | What the module does |
+
+### After Creating
+
+1. Add to `modules/nixos/default.nix` imports
+2. Optionally export from `flake.nix` `nixosModules`
+3. Add documentation to `docs/modules/nixos/`
+4. Run `nix flake check`
+
+## Home Manager Module Template
+
+Creates a complete Home Manager module:
+
+```
+templates/home-manager-module/
+├── default.nix    # Module with options
+└── README.md       # Module documentation
+```
+
+### Fields to Fill In
+
+| Field | Location | Notes |
+|-------|----------|-------|
+| Category | Directory | Choose `cli/` or `coding/` |
+| Options | `default.nix` | Add under `options.m3ta.<name>` |
+| Config | `default.nix` | Add under `config.m3ta.<name>` |
+| Description | `README.md` | What the module does |
+
+### After Creating
+
+1. Add to the appropriate category aggregator (`cli/default.nix` or `coding/default.nix`)
+2. Optionally export from `flake.nix` `homeManagerModules`
+3. Add documentation to `docs/modules/home-manager/`
+4. Run `nix flake check`
+
+## Template Variables
+
+Templates use Nix attribute references. After copying, search for these placeholders:
+
+| Placeholder | Replace With |
+|-------------|--------------|
+| `package-name` | Your package name (kebab-case) |
+| `owner-name` / `repo-name` | GitHub owner and repo |
+| `0.1.0` | Initial version |
+| `lib.fakeHash` | Real hash after first build |
+| `lib.licenses.mit` | Appropriate license |
+| `A short description` | One-line description |
+
+## Automated Updates
+
+Packages created from templates are automatically updated weekly by the Gitea Actions workflow. See the main README for details on the `nix-update` automation.
+
+## Related
+
+- [Adding Packages](./guides/adding-packages.md) - Detailed package guide
+- [Adding Modules](./guides/adding-modules.md) - Detailed module guide
+- [Development Workflow](./guides/development-workflow.md) - Local development
+- [Architecture](./ARCHITECTURE.md) - Repository structure