Add in-repo docs for the Devlib project

docs/Architecture.md

@@ -0,0 +1,23 @@
+<!-- owner: shikanime | zone: internal | purpose: module set and design -->
+# Architecture
+
+`devlib` exposes flake outputs consumed by other repos:
+
+- `devenvModule` — enables all integrated generators (gitignore, GitHub
+  workflows, renovate, sops, …).
+- `devenvModules.<name>` — composable profiles (`git`, `nix`, `shell`,
+  `go`, `javascript`, `rust`, `docker`, `elixir`, `ocaml`, …) for a
+  `devenv.shell`.
+- `homeModule` / `homeModules.<name>` — Home Manager modules.
+- `flakeModule` — a flake-parts module exposing `treefmt` + `pre-commit`
+  from a chosen `devenv.shell`.
+
+Modules live under `modules/` (`devenv/`, `home/`, `flake/`). `devenv/`
+splits into `integrations/` (air, buf, ghstack, github, gitignore, license,
+renovate, sops), `profiles/` (per-language shells), and `shells/`.
+`templates/` holds `default` and `remote` scaffolds (`AGENTS.md`, `flake.nix`).
+
+## Design intent
+
+One source of truth for dev-environment hygiene, so every shikanime repo
+gets the same git-hooks, formatting, and CI wiring by importing a profile.

docs/Development.md

@@ -0,0 +1,21 @@
+<!-- owner: shikanime | zone: internal | purpose: local check loop -->
+# Development
+
+## Prerequisites
+
+- Nix (flakes) and `direnv` — `direnv allow`.
+
+## Local loop
+
+```bash
+direnv allow
+nix flake check     # evaluate every module/system
+nix fmt             # treefmt over Nix/Markdown
+```
+
+## How to add a module
+
+1. Add a `.nix` under `modules/devenv/integrations` or `profiles`.
+2. Export it from `flake.nix` (e.g. `devenvModules.<name>`).
+3. Run `nix flake check`; add a consumer test if it touches outputs.
+4. `nix fmt`, then open a PR (stack workflow in `AGENTS.md`).

docs/README.md

@@ -0,0 +1,18 @@
+<!-- owner: shikanime | zone: internal | purpose: index of internal-ops docs -->
+# Devlib — internal docs
+
+A collection of Nix flake modules that bootstrap a reproducible developer
+experience with `devenv`, `git-hooks`, and `treefmt`, plus generator
+templates for new repos.
+
+## Internal ops
+
+- [Architecture](./Architecture.md) — module set and what each exposes
+- [Development](./Development.md) — local check loop
+- [Runbook](./Runbook.md) — consume a module, release
+- [Troubleshooting](./Troubleshooting.md) — common Nix failures
+- [Reference](./Reference.md) — exported modules and profiles
+
+## User-facing docs
+
+- [README.md](../README.md) — quick start and module reference

docs/Reference.md

@@ -0,0 +1,20 @@
+<!-- owner: shikanime | zone: internal | purpose: exported modules -->
+# Reference
+
+## Exported flake outputs
+
+- `devenvModule` — all-in-one generator module.
+- `devenvModules.<name>` — profiles: `base`, `default`, `git`, `go`,
+  `javascript`, `nix`, `rust`, `docker`, `elixir`, `ocaml`, `shell`, …
+- `homeModule` / `homeModules.<name>` — Home Manager modules.
+- `flakeModule` — flake-parts module (treefmt + pre-commit).
+
+## Integrations
+
+`air`, `buf`, `ghstack`, `github` (cleanup/commands/integration/javascript/
+nix/release/skaffold/triage), `gitignore`, `license`, `renovate`, `sops`.
+
+## Templates
+
+- `templates.default` — `AGENTS.md` + `flake.nix` for a new repo.
+- `templates.remote` — remote-scaffold variant.

docs/Runbook.md

@@ -0,0 +1,26 @@
+<!-- owner: shikanime | zone: internal | purpose: consume/release -->
+# Runbook
+
+## Consume
+
+Add `devlib` to a flake's inputs (following `README.md`), then import
+profiles into a `devenv.shell`:
+
+```nix
+perSystem = _: {
+  devenv.shells.default.imports = [
+    inputs.devlib.devenvModules.git
+    inputs.devlib.devenvModules.nix
+  ];
+};
+```
+
+## Release
+
+No published version; consumers pin a git ref. Bump the ref in the
+consuming repo when a module changes.
+
+## Branch protection
+
+`main` is protected (1 review, linear history, signed commits). Land with
+`gh stack merge`. Test modules with `nix flake check` before submitting.

docs/Troubleshooting.md

@@ -0,0 +1,23 @@
+<!-- owner: shikanime | zone: internal | purpose: known Nix failures -->
+# Troubleshooting
+
+## `nix flake check` fails on a new system
+
+Modules are evaluated per-system. A profile that assumes a tool absent on
+some platform breaks `check`. Guard with `lib.optionalAttrs` / `mkIf`.
+
+## treefmt reformats unexpectedly
+
+`nix fmt` formats Markdown/Nix/YAML repo-wide. If CI reports drift, run
+`nix fmt` locally and commit; never widen the formatter config to hide it.
+
+## Wrong profile applied
+
+Profiles are composed by import list, not auto-detected. A missing
+`devenvModules.<lang>` means that language's tooling is absent — add it to
+the shell imports.
+
+## Consumer flake broke after bump
+
+Devlib keeps backward compatibility with consumer flakes. If a bump breaks
+yours, pin the last-known-good ref and file an issue.