docs: add repository context docs 🤖🤖🤖

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.

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.

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.

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.

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/`.

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.

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`.

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.