docs(devcontainer-features-ai-coding): 📚️ 📝 rewrite root README, add README conventions

.agents/instructions/readme.instructions.md

@@ -0,0 +1 @@
+../../src/ai-coding/stubs/.agents/instructions/readme.instructions.md

.github/instructions/readme.instructions.md

@@ -0,0 +1 @@
+../../.agents/instructions/readme.instructions.md

README.md

@@ -2,54 +2,25 @@
 
 # Dev Container Features
 
-This repository contains a collection of features that can be used to enhance the development experience in a [Visual Studio Code Dev Container](https://code.visualstudio.com/docs/remote/containers).
+Ready-made [Dev Container](https://containers.dev) features for git workflow,
+commit hooks, versioning, AI coding skills, Kubernetes and more. Pick the ones
+you need; each is independent and documents its own options.
 
-The features are organized in separate folders and can be used individually in a `devcontainer.json` file.
+## Quick start
 
-## Installation
+Add features to `.devcontainer/devcontainer.json`:
 
-Every feature in this repository can be installed three ways. Pick whichever fits where you're running:
-
-1. **As a devcontainer feature** — declare it in `.devcontainer/devcontainer.json`; the Dev Containers CLI / VS Code builds it into the container image. Nothing to run locally. See each feature's own `## Quick Start — devcontainer.json` below.
-2. **Console, via `npx`** — requires Node.js/npm on the machine you run it from (host or inside the container). Resolves this repo from GitHub and runs `install.sh`.
-    ```sh
-    npx tomgrv/devcontainer-features -h
-    ```
-3. **Console, via `curl`** — no Node.js/npm required. Downloads this repo to a temp directory, runs `install.sh`, and cleans up after itself:
-    ```sh
-    curl -fsSL https://raw.githubusercontent.com/tomgrv/devcontainer-features/develop/setup.sh | sh -s -- -h
-    ```
-    Everything after `-s --` is forwarded to `install.sh` — same commands/targets as the `npx` form. Set `DEVCONTAINER_FEATURES_REF` to install from a different branch, tag, or commit.
-
-Methods 2 and 3 both run `install.sh`, which behaves the same on a host and inside a container (Codespaces, an already-running devcontainer): it installs the tool itself (binaries, git config, package-manager installs where a feature needs one, ...) and deploys the feature's stub files (`.devcontainer/`, `.github/`, editor config, ...) into the current project. A handful of steps genuinely only make sense in one context or the other (e.g. gateway's host CA trust-store setup, or diverting `curl` only by default inside a container) — those scripts detect where they're running and adjust themselves; you don't need to.
-
-#### To install only root stubs
-
-```sh
-npx tomgrv/devcontainer-features -- init
-# or, without node/npm:
-curl -fsSL https://raw.githubusercontent.com/tomgrv/devcontainer-features/develop/setup.sh | sh -s -- init
-```
-
-#### To install a specific devcontainer feature
-
-```sh
-npx tomgrv/devcontainer-features -- add gitutils
-# or, without node/npm:
-curl -fsSL https://raw.githubusercontent.com/tomgrv/devcontainer-features/develop/setup.sh | sh -s -- add gitutils
-```
-
-#### To set up a full dev environment
-
-```sh
-npx tomgrv/devcontainer-features -- add -a
-# or, without node/npm:
-curl -fsSL https://raw.githubusercontent.com/tomgrv/devcontainer-features/develop/setup.sh | sh -s -- add -a
+```json
+"features": {
+    "ghcr.io/tomgrv/devcontainer-features/gitutils:11": {},
+    "ghcr.io/tomgrv/devcontainer-features/githooks:11": {}
+}
 ```
 
-## Features Overview
+Rebuild the container and they are ready. The id is always
+`ghcr.io/tomgrv/devcontainer-features/<feature>:11`.
 
-Each row's console command is `add <feature>` (see [Installation](#installation)); the devcontainer.json id is `ghcr.io/tomgrv/devcontainer-features/<feature>:11`; the npm package is `@tomgrv/devcontainer-features-<feature>`.
+## Features
 
 | Feature                                      | `<feature>`    | Description                                                               |
 | -------------------------------------------- | -------------- | ------------------------------------------------------------------------- |
@@ -64,14 +35,40 @@ Each row's console command is `add <feature>` (see [Installation](#installation)
 | [Scripting](./src/scripting/README.md)       | `scripting`    | Standard root `setup.sh` bootstrapping `zz-use` and the repo entrypoint   |
 | [AI Coding](./src/ai-coding/README.md)       | `ai-coding`    | Agent-agnostic AI coding skills + Claude Code GitHub Action               |
 
-## MCP server for agents
+Each feature has its own README with its options and commands.
+
+## Install without a dev container
+
+The same features install from a terminal on any machine (host, Codespaces,
+running container). They set up the tool and copy the feature's files
+(`.devcontainer/`, `.github/`, editor config...) into the current project.
+
+```sh
+npx tomgrv/devcontainer-features -- add gitutils   # one feature
+npx tomgrv/devcontainer-features -- add -a         # all of them
+npx tomgrv/devcontainer-features -- init           # root files only
+npx tomgrv/devcontainer-features -h                # all commands
+```
+
+No Node.js? Use curl instead (everything after `-s --` is passed through):
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/tomgrv/devcontainer-features/develop/setup.sh | sh -s -- add gitutils
+```
+
+Set `DEVCONTAINER_FEATURES_REF` to install from another branch, tag or commit.
+Features are also published to npm as `@tomgrv/devcontainer-features-<feature>`.
+
+## Let an agent set it up
 
-An MCP server under [`.mcp/`](./.mcp/README.md) lets an agent list features, read their docs, and get the exact setup command — so it can bootstrap another repo's dev environment without crawling this README by hand.
+An [MCP server](./.mcp/README.md) lets an AI agent list the features, read their
+docs and get the exact setup command for another repository.
 
 ## Contributing
 
-If you have a feature that you would like to add to this repository, please open an issue or submit a pull request.
+Open an issue or a pull request against `develop`. Commit and PR title rules:
+[`CLAUDE.md`](./CLAUDE.md).
 
 ## License
 
-This repository is licensed under the [MIT License](./LICENSE).
+[MIT](./LICENSE).

src/ai-coding/stubs/.agents/instructions/readme.instructions.md

@@ -0,0 +1,24 @@
+---
+applyTo: '**/README.md'
+---
+
+<!-- @format -->
+
+## README Conventions
+
+Applies to every README in every repo of the family (`scripts`, `actions`, `devcontainer-features`, `vps`).
+
+### Any README (tool, action, feature, step)
+
+- **Consistent, coherent, simple, pragmatic.** Same section order across siblings; no repeated boilerplate; say it once.
+- **Same skeleton per repo.** Title, one-line purpose, `Usage`/`Inputs`/`Options`, `Outputs`/`Environment variables`, `Dependencies`, `Tests`, `Example`. Keep what the siblings have, add what they lack.
+- **Facts come from the code.** Usage and options from the script's `-h` or `zz-args` spec, inputs and outputs from `action.yml`, options and defaults from `devcontainer-feature.json`, variables from `package.json` `config`. When code and README disagree, fix the README.
+- **Header and format.** First line `<!-- @format -->`; run `prettier` on the file before committing (4-space indent in lists).
+- **Link, don't duplicate.** Document a tool once, in its own README; other READMEs link to it.
+
+### Root README
+
+- **User oriented, current usage only.** The first screen gets a reader from zero to a working install or run: what it is, a copy-paste quick start, then a catalog of what is available with one line each.
+- **Exclude** past decisions, legacy flags and layouts, migration notes, "why we did it this way", internal design, test counts and release plumbing. Those belong in `UPGRADING.md`, `CHANGELOG.md` or `docs/`.
+- **Keep** only what a user needs next: inputs they must provide, how to choose or remove parts, how to verify it worked, troubleshooting, and a short Contributing section (how to run tests, which branch to target).
+- **Order:** purpose, quick start, catalog, how-to sections, troubleshooting, contributing, license.

src/ai-coding/stubs/.github/instructions/readme.instructions.md

@@ -0,0 +1 @@
+../../.agents/instructions/readme.instructions.md