# AGENTS.md

> harden-ci is one document, `README.md`: instructions that AI agents follow to audit a repository and make its CI/CD secure. This repository holds that document and the build that publishes it at https://harden-ci.secmy.app/. This file is for agents that change harden-ci itself.

If you were asked to apply harden-ci to another repository, this file is not for you. Read `README.md` and follow it

## Project layout

- `README.md` - the document. It is the only source of the published text
- `site/build.sh` - builds the site into `_site/`
- `site/check.sh` - checks the built site
- `site/style.css`, `site/footer.html`, `site/toc.lua` - the look of the HTML page, its footer, and a filter that puts the title above the table of contents
- `site/head.html` - description, canonical address, icons and social preview tags for the HTML page
- `site/assets/` - the icon and the social preview image. Each PNG is rendered from the SVG next to it
- `site/llms.txt`, `site/robots.txt`, `site/ai.txt`, `site/sitemap.xml` - published as they are
- `.github/workflows/pages.yml` - runs the build and the check on every pull request, and publishes from `main`

## Build and check

You need Docker with a running daemon. Run both commands from the repository root:

```sh
sh site/build.sh
sh site/check.sh
```

Both must exit with code 0. `site/check.sh` prints `all checks passed`. There are no other tests. The same two commands run in CI

## Published files

All of these are generated by `site/build.sh`. Do not edit anything in `_site/`

| URL | Source |
|---|---|
| `/` | `README.md` converted to HTML, plus `site/footer.html` |
| `/README.md`, `/index.md`, `/llms-full.txt` | exact copies of `README.md` |
| `/AGENTS.md` | exact copy of this file |
| `/llms.txt`, `/robots.txt`, `/ai.txt`, `/sitemap.xml` | exact copies from `site/` |
| `/favicon.svg`, `/favicon-32.png`, `/apple-touch-icon.png`, `/social-preview.png` | exact copies from `site/assets/` |

If you add a published file, add it to `site/build.sh`, to `site/check.sh` and to this table. If it is a document for readers, add it to `site/sitemap.xml` and to `site/llms.txt` too

If you change an SVG in `site/assets/`, render its PNG again at the same size (social preview 1200x630, touch icon 180x180, favicon 32x32) and commit both. The build does not render images. If you change the title or the summary of the document, update `site/head.html`, `site/llms.txt` and the social preview image too

The crawler policy is: everything is allowed, for search, for fetching on a user's behalf and for training. `site/robots.txt` and `site/ai.txt` must agree with it

## Conventions for README.md

- plain English and short sentences. The text speaks to the agent as "you"
- use the hyphen `-`, not a long dash. Do not put a period at the end of a paragraph or a list item
- every requirement says what priority a finding has: critical, high, medium or low
- do not write versions, image digests or commit SHAs of tools in `README.md`. The agent that reads it finds them
- name a tool only after you checked it in its official source. Say whether it is the author's choice or a starting point
- when you add, remove or move a step, update every reference to step numbers: the stage description in "How to work", cross references inside the steps, and the "Report" section

## Conventions for the workflow and scripts

- pin every action by its full commit SHA, with the version in a comment
- pin every image by digest, and keep the tag next to the digest
- use versions that are at least 7 days old. Read SHAs and digests from GitHub and from the registry, not from memory
- never write a `${{ ... }}` expression that holds data from a pull request inside `run:`
- the workflow token stays read-only. Only the `deploy` job has write permissions

## How to change this repository

- create a branch from `main` and open a pull request. One topic per pull request
- the `main` branch does not accept direct pushes, unsigned commits or force pushes
- sign your commits with the key that is set up in git. Do not use `--no-gpg-sign`
- do not add AI attribution lines to commit messages or pull request text
- wait until the `build` check passes. Merge a pull request only when the user asks you to

## Do not

- do not rewrite git history, force push, or delete branches and tags
- do not change repository settings, rulesets, Pages settings or DNS
- do not keep a second copy of the document text in the repository. The published copies come from `README.md` at build time
- do not weaken or remove a check in `site/check.sh` to make the build pass