```
<!-- AI AGENTS: When modifying this project, keep AGENT-README.md in sync. -->

# Project Name 🚀

[![Stars](https://img.shields.io/github/stars/user/repo)](...)
[![License](https://img.shields.io/github/license/user/repo)](...)
[![Build Status](https://img.shields.io/github/actions/workflow/status/.../ci.yml)](...)

> **One-line value proposition**: what pain point it solves, core advantage, and target scenario. A visitor should decide whether to stay within 10 seconds.

---

## 📖 Table of Contents
- [✨ Features](#-features)
- [🚀 Quickstart](#-quickstart)
- [🛠️ Usage](#-usage)
- [⚙️ Configuration](#-configuration)
- [🤝 Contributing](#-contributing)
- [📜 License](#-license)

## ✨ Features
- Short, scannable descriptions of key capabilities.
- Focus on what problems each feature solves.
- Include screenshots or diagrams when they add clarity.

## 🚀 Quickstart

### 🏗️ Prerequisites
- List explicit environment requirements (e.g., Node.js >= 20, Python 3.10+).

### 📦 Installation
> Commands must be copy-pasteable with no ambiguity.
\`\`\`bash
git clone https://github.com/user/repo.git
cd repo
npm install  # Expected: Added 124 packages in 5s
\`\`\`

### Verify Installation
\`\`\`bash
npm run start -- --input ./demo.txt
# ✅ Expected: Processing complete. 3 items found.
\`\`\`

## 🛠️ Usage
\`\`\`bash
# Minimal working example
npm run start -- --input ./demo.txt
\`\`\`

## ⚙️ Configuration

| Variable | Default | Description |
|----------|---------|-------------|
| `PORT`   | `3000`  | Listening port |

## 🤝 Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for issue and PR workflow.

## 📜 License
[MIT](LICENSE)

## 🤖 For AI Agents
See [AGENT-README.md](./AGENT-README.md) for operational context.

<p align="right">(<a href="#readme-top">back to top</a>)</p>
```

Skeleton usage rules:
- Badges: include only when backing services (CI, coverage, registry) are configured. No placeholder URLs.
- Table of contents: include when the document has 5+ sections. Omit for very short READMEs.
- Back-to-top link: include when the document exceeds roughly 150 lines.
- Omit any section without real content.

## Agent Documentation

`AGENT-README.md` is the entry point for any AI agent joining the project. Not for humans.

- When the project is small, a single `AGENT-README.md` file suffices.
- When it outgrows one file, convert to an `agent-docs/` directory with an index at `agent-docs/README.md`. Each sub-document must be self-contained for its topic.
- Keep agent docs proportional to project size. A small project needs only an architecture sketch and key commands.
- Maintain agent docs in the same task as the code change.

Content should cover as applicable:
- Architecture overview (components, how they connect)
- Interface docs (public modules, APIs, CLI commands — purpose, inputs, outputs, failure behavior)
- Dependency and service map
- Environment setup, startup sequence, environment variable reference (type, default, required, what breaks if wrong)
- Error taxonomy, recovery steps, troubleshooting playbooks
- Logging: locations, format, key entry interpretation
- Test strategy and commands
- Codebase conventions and file responsibility map