docs: align documentation with actual repo state

AGENTS.md

@@ -4,39 +4,23 @@ Instructions for AI coding agents working in this repository.
 
 ## Project Overview
 
-This is a general-purpose GitHub repository template. It contains community health files, a baseline CI workflow, and a starter GitHub Pages page. New repositories created from this template should customize these files for their own stack.
-
-## Repository Structure
-
-| Path | Purpose |
-|---|---|
-| `index.html` | GitHub Pages entry point |
-| `.github/workflows/ci.yml` | Generic CI workflow (Node steps skip when no `package.json` exists) |
-| `.gitignore` | General-purpose ignore rules (OS, editors, env files, common build artifacts) |
-| `CONTRIBUTING.md` | Contribution guidelines |
-| `CODE_OF_CONDUCT.md` | Contributor Covenant v2.1 |
-| `SECURITY.md` | Security policy |
-| `LICENSE` | MIT License |
+This is a general-purpose GitHub repository template. It contains community health files and a baseline CI workflow. New repositories created from this template should customize these files for their own stack. `README.md` carries the file inventory.
 
 ## Guidelines
 
 - Keep changes minimal and aligned with the repo's existing style.
 - Do not commit secrets or environment files (`.env`); use `.env.example` instead.
 - Run available linters/formatters/tests before declaring work complete; if none exist, say so.
-- Prefer small, focused commits with descriptive messages.
+- Prefer small, focused commits; write subjects as `type(scope): summary` (see `CONTRIBUTING.md`).
 - Use branch naming prefixes: `feat/`, `fix/`, `docs/`, `chore/`, `refactor/`, `test/` (see `CONTRIBUTING.md`).
 - Open PRs early and keep them small — a series of small, merged PRs is easier to review than one large one.
 - Report honestly: state what was tested, what failed, and what was skipped.
 
-## Tips
-
-- Don't change the core apps unless you find a real bug.
-
 ## Customization Checklist
 
 When using this template for a new project:
 
 1. Replace this file with project-specific agent instructions (commands, conventions, architecture notes).
-2. Update `README.md`, `SECURITY.md` links, and the contact method in `CODE_OF_CONDUCT.md`.
+2. Update `README.md` and the reporting contact in `SECURITY.md`.
 3. Adjust `.github/workflows/ci.yml` for the project's language and test runner.
 4. Trim `.gitignore` to the project's stack if desired.

CONTRIBUTING.md

@@ -21,11 +21,38 @@ Use lowercase prefixes with a short description separated by a slash:
 
 Example: `feat/user-auth`, `fix/login-crash`, `docs/api-endpoints`.
 
+Avoid parentheses and other shell metacharacters in branch names. Git accepts
+them, but `bash` and `zsh` treat `(` as syntax, so `git push origin fix(x)`
+fails with a syntax error unless quoted every time.
+
+## Commit Messages
+
+Write commit subjects as `type(scope): summary`, using the same types as the
+branch prefixes above. The scope is optional — omit it when a change is
+repo-wide.
+
+| Part | Rule |
+|---|---|
+| `type` | One of `feat`, `fix`, `docs`, `chore`, `refactor`, `test` |
+| `scope` | Optional area touched, lowercase (e.g. `security`, `ci`, `agents`) |
+| `summary` | Imperative mood, no trailing period, ideally under 72 characters |
+
+Examples:
+
+```
+fix(security): point disclosure at the advisory form
+docs(agents): drop the duplicated file inventory
+chore(ci): pin actions to commit SHAs
+```
+
+Use the body to explain why the change was made, not what the diff already
+shows. State only what you actually verified.
+
 ## Pull Requests
 
 1. Fork the repository.
 2. Create a branch using the naming convention above (`git checkout -b feat/my-feature`).
-3. Make your changes and commit with a descriptive message.
+3. Make your changes and commit using the message format above.
 4. Push to your branch (`git push origin feat/my-feature`).
 5. Open a pull request.
 

README.md

@@ -9,10 +9,10 @@ A starter template for new GitHub repositories.
 | `LICENSE` | MIT License |
 | `.gitignore` | General-purpose gitignore (OS, editor, env, and common build artifacts) |
 | `CONTRIBUTING.md` | Guidelines for contributing |
-| `CODE_OF_CONDUCT.md` | Contributor Covenant v2.1 |
 | `SECURITY.md` | Security policy |
-| `.github/workflows/ci.yml` | Generic GitHub Actions CI workflow |
-| `AGENTS.md` | Instructions for AI coding agents (`CLAUDE.md` imports it) |
+| `.github/workflows/ci.yml` | Generic GitHub Actions CI workflow (the `npm ci` and `npm test` steps skip when no `package.json` exists) |
+| `AGENTS.md` | Instructions for AI coding agents |
+| `CLAUDE.md` | Imports `AGENTS.md` so Claude Code picks up the same instructions |
 
 ## How to use