# README Maintenance

> These rules are written for Claude Code but the concepts apply to any AI agent system.

## The Pattern: Human README + Agent Entrypoint

Every repo in this system follows a hybrid pattern:

- `README.md` — human-facing landing page (GitHub/Forgejo renders this first)
- `LLM-ENTRYPOINT.md` (or equivalent) — agent-facing startup chain

These are not duplicates. They serve different audiences and must both exist. Never collapse them into one file. Never let README.md become agent instructions.

## README.md Must Contain

1. **What this repo is** — one paragraph, plain English
2. **Current state table** — key services/components and their live status
3. **Key documents table** — links to the most important docs an operator needs
4. **Repo structure** — top-level directory layout with one-line descriptions
5. **Branch model** — who owns which branch and its purpose
6. **Agent entry point note** — a single line at the bottom: `*Agent entry point: LLM-ENTRYPOINT.md*`

## When to Update README.md

Update README.md when **state changes**, not when work happens:

| Trigger | README update required |
|---------|----------------------|
| A service goes live or is decommissioned | Yes — update current state table |
| A new key document is created | Yes — add to key documents table |
| Repo top-level structure changes | Yes — update structure section |
| Existing state entry becomes stale | Yes — update it |
| Routine commit (config fix, doc edit) | No |
| Bug fix or minor feature work | No |

**Rule:** If the commit message would reasonably include the word "add", "remove", or "complete" for a system component or major document, check whether the README current state table needs updating.

## When Creating a New Repo

Before the first meaningful commit, write a README.md with all five sections above. A stub README is not acceptable as a permanent state.

## What README.md Must NOT Contain

- Agent startup chains or read-order instructions (those go in LLM-ENTRYPOINT.md)
- Secrets, tokens, or credential paths
- Internal agent coordination details
- Architecture deep-dives (link to the relevant doc instead)