diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..0c4907c
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,35 @@
+# AGENTS.md
+
+Guidance for AI coding agents working in this repository.
+
+## Start Here
+
+Before making changes, read:
+
+- `CONTRIBUTING.md` for contribution, PR, testing, commit, and agent-specific expectations.
+- `RELEASE.md` for release workflow details.
+- `README.md` for user-facing behavior, install/use examples, and package or app overview.
+- `docs/README.md` for the project documentation index.
+- `docs/development.md` for local setup and development workflows.
+- `docs/testing.md` for test strategy, commands, and verification expectations.
+- `docs/architecture.md` for project structure, boundaries, and important invariants.
+- `docs/conventions.md` for project-specific coding, documentation, and maintenance conventions.
+
+Treat those files as the source of truth. Do not duplicate or reinterpret their rules here.
+
+## Documentation
+
+- Keep documentation in sync when changing behavior, public interfaces, workflows, architecture, configuration, or operational assumptions.
+- Put project-specific development details in `docs/`; keep root files focused on their standard audiences.
+- Prefer linking to the source of truth over duplicating long instructions across files.
+- When adding new docs, link them from `docs/README.md` and update this file only when they become important entry points for future agents.
+
+## PRs and Issues
+
+- Follow PR, issue, and agent-labeling rules in `CONTRIBUTING.md`.
+- Use the issue-linking format specified in `CONTRIBUTING.md`.
+
+## Releases
+
+- Follow `RELEASE.md` for release workflow and changeset creation steps.
+- If this project uses changesets, treat `RELEASE.md` and any changeset guidance in `CONTRIBUTING.md` as authoritative.
diff --git a/README.md b/README.md
index 32a30cf..fb349ee 100644
--- a/README.md
+++ b/README.md
@@ -75,3 +75,7 @@ docker build --tag lirantal/travis-cli .
 
 # Author
 Liran Tal <liran.tal@gmail.com>
+
+## Documentation
+
+- [Project documentation](./docs/README.md) - development, testing, architecture, and conventions.
diff --git a/RELEASE.md b/RELEASE.md
new file mode 100644
index 0000000..2bb73e2
--- /dev/null
+++ b/RELEASE.md
@@ -0,0 +1,22 @@
+# Release
+
+This project uses [Changesets](https://github.com/changesets/changesets) for versioning and release notes.
+
+## Release Flow
+
+1. Ensure all intended changes are merged and CI is green.
+2. Run `pnpm version` to apply Changesets version and changelog updates.
+3. Review the generated package and changelog changes.
+4. Run the release command, if configured for the repository.
+
+No root `release` script is currently defined. Use the repository's publishing workflow or add one before publishing.
+
+## Changesets
+
+Add a changeset for user-facing package behavior changes:
+
+```sh
+pnpm changeset
+```
+
+Documentation-only, test-only, and internal refactor PRs usually do not need a changeset unless they describe or accompany a release-worthy behavior change.
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..c8fce7c
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,16 @@
+# docker-travis-cli Documentation
+
+This directory contains project documentation for maintainers and coding agents.
+
+## Core Docs
+
+- [Development](./development.md) - local setup, workflows, and useful commands.
+- [Testing](./testing.md) - test commands, test organization, and verification expectations.
+- [Architecture](./architecture.md) - repository structure, package boundaries, and important flows.
+- [Conventions](./conventions.md) - coding, documentation, and maintenance conventions.
+
+## Root References
+
+- [Project README](../README.md) - user-facing overview, installation, and usage.
+- [Contributing](../CONTRIBUTING.md) - issue, PR, commit, and agent expectations.
+- [Release](../RELEASE.md) - Changesets and release workflow.
diff --git a/docs/architecture.md b/docs/architecture.md
new file mode 100644
index 0000000..f537966
--- /dev/null
+++ b/docs/architecture.md
@@ -0,0 +1,18 @@
+# Architecture
+
+## Overview
+
+docker-travis-cli contains the source, package configuration, and release tooling for `docker-travis-cli`.
+
+## Repository Structure
+
+- `package.json` - root package scripts and dependency metadata.
+- `.changeset/` - Changesets configuration and pending release notes.
+- `docs/` - project documentation for maintainers and coding agents.
+
+## Boundaries
+
+- Keep user-facing usage, installation, and examples in the root `README.md`.
+- Keep contribution rules in `CONTRIBUTING.md`.
+- Keep release workflow details in `RELEASE.md`.
+- Keep deeper development and architecture notes in `docs/`.
diff --git a/docs/conventions.md b/docs/conventions.md
new file mode 100644
index 0000000..8004f5d
--- /dev/null
+++ b/docs/conventions.md
@@ -0,0 +1,20 @@
+# Conventions
+
+## Commits and PRs
+
+- Use Conventional Commits for commit messages.
+- Keep PRs focused on one logical change.
+- Include a Changeset for release-worthy package behavior changes.
+- Agent-authored PRs should follow the repository's agent title marker guidance in `CONTRIBUTING.md`.
+
+## Documentation
+
+- Keep root `README.md` focused on users and package consumers.
+- Put maintainer and agent context in `docs/`.
+- Link new documentation from `docs/README.md`.
+
+## Code
+
+- Prefer the existing package structure and scripts over introducing new tooling.
+- Keep generated files, dependency folders, and build output out of commits.
+- Match formatting and lint expectations already configured in the repository.
diff --git a/docs/development.md b/docs/development.md
new file mode 100644
index 0000000..c5eb7a2
--- /dev/null
+++ b/docs/development.md
@@ -0,0 +1,20 @@
+# Development
+
+## Prerequisites
+
+- Node.js compatible with this repository's packages and tooling.
+- pnpm for dependency installation and scripts.
+
+## Setup
+
+```sh
+pnpm install
+```
+
+## Common Commands
+
+- TODO: Document the common local development commands for this repository.
+
+## Repository Notes
+
+This repository is organized around the root package `docker-travis-cli`.
diff --git a/docs/testing.md b/docs/testing.md
new file mode 100644
index 0000000..4979854
--- /dev/null
+++ b/docs/testing.md
@@ -0,0 +1,12 @@
+# Testing
+
+## Test Command
+
+TODO: Document the primary test command for this repository.
+
+
+## Expectations
+
+- Add or update tests for behavior changes.
+- Run the relevant package-level checks before opening a PR.
+- Keep generated coverage, build output, and dependency folders out of commits.