> For the complete documentation index, see [llms.txt](https://docs.shiftiq.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.shiftiq.com/contributors/conventions/readme-files.md).

# README files

README first: explain what it is, what it does, and how to use it

A README is a short summary of the contents of a directory. It provide critical information for people browsing your code, especially first-time users.

The contents of the file are displayed in GitHub when you view the contents of the containing directory. For example, the README.md file is rendered when you view the contents of the containing directory:

* [Style guides for Google open-source projects](https://github.com/google/styleguide/tree/gh-pages)

## Readable README files <a href="#readable-readme-files" id="readable-readme-files"></a>

README files must be named `README.md`

The file name must be uppercase `README`, and the file extension must be lowercase `md` .

This causes it to stand out — because lowercase and Title Case filenames are much more common. Also, on [Unix-like](https://en.wikipedia.org/wiki/Unix-like) systems, the [`ls`](https://en.wikipedia.org/wiki/Ls) command sorts and displays files in [ASCII-code order](https://en.wikipedia.org/wiki/ASCIIbetical), so uppercase filenames appear first.

## Where to put your README <a href="#where-to-put-your-readme" id="where-to-put-your-readme"></a>

`README.md` files should be located in the top-level directory for each library's codebase.

All top-level directories for a source code package should have a current `README.md` file. This is especially important for package directories that provide interfaces for other teams.

## What to put in your README <a href="#what-to-put-in-your-readme" id="what-to-put-in-your-readme"></a>

At a minimum, your `README.md` file should contain a link to user- and/or team-facing documentation.

Every package-level `README.md` should include (or link to) the following information:

1. A summary of the purpose and contents of the package or library.
2. A list of relevant contacts.
3. The status of the package or library. For example, is it deprecated, not for general release, etc.
4. A description of how to use the package or library.
5. Links to additional relevant documentation.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.shiftiq.com/contributors/conventions/readme-files.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
