> 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

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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.