docs: add progressive agent instructions

Author: masterkain

AGENTS.md

@@ -0,0 +1,20 @@
+# Repository Guidelines
+
+Docker image wrapper around the official Bitwarden CLI, with Renovate-tracked
+upstream version bumps and GHCR publishing on `main`.
+
+## Quick Reference
+
+- `docker build -t bitwarden-cli-docker:local .`: local image build
+- `shellcheck entrypoint.sh`: shell lint
+- `actionlint .github/workflows/build.yml`: workflow lint
+- `docker run --rm -v "$PWD:/usr/src/app" -w /usr/src/app \`
+  `renovate/renovate:latest renovate-config-validator`: validate Renovate
+  config
+
+## Detailed Instructions
+
+- [Architecture & Layout](agent-instructions/architecture.md)
+- [Runtime Behavior](agent-instructions/runtime.md)
+- [Testing & Verification](agent-instructions/testing.md)
+- [Release Workflow](agent-instructions/release-workflow.md)

agent-instructions/architecture.md

@@ -0,0 +1,20 @@
+# Architecture & Layout
+
+## Overview
+
+Use this file when deciding where image, runtime, or automation changes belong.
+
+## Project Structure
+
+- `Dockerfile`: tracked Bitwarden CLI version and image build logic
+- `entrypoint.sh`: runtime wrapper for passthrough CLI mode and `bw serve`
+- `.github/workflows/build.yml`: PR build plus `main` publish flow
+- `renovate.json`: upstream version-tracking rules for `BW_VERSION`
+- `README.md`: operator-facing usage and runtime guidance
+
+## Placement Rules
+
+- Put Bitwarden CLI version tracking in `Dockerfile`
+- Keep runtime behavior in `entrypoint.sh`
+- Keep publish automation in GitHub Actions, not ad hoc shell scripts
+- Document operator-facing changes in `README.md`

agent-instructions/release-workflow.md

@@ -0,0 +1,20 @@
+# Release Workflow
+
+## Overview
+
+Use this file when changing upstream version tracking or publish automation.
+
+## Rules
+
+- `BW_VERSION` in `Dockerfile` is the single tracked source of the bundled CLI
+  version
+- Renovate is responsible for proposing upstream Bitwarden CLI bumps
+- Pull requests should build the image without publishing
+- Pushes to `main` publish the image tag that matches `BW_VERSION`
+
+## Avoid
+
+- Do not reintroduce keepalive commits or cron-driven "stay active" workflows
+- Do not add out-of-repo state such as S3 revision markers for version tracking
+- Do not bypass the tracked `BW_VERSION` by auto-resolving latest tags inside
+  the workflow

agent-instructions/runtime.md

@@ -0,0 +1,19 @@
+# Runtime Behavior
+
+## Overview
+
+Use this file when changing container startup behavior or `/bw` state handling.
+
+## Entrypoint Rules
+
+- Passing explicit arguments should remain a direct passthrough to `bw`
+- No-argument startup is the managed `bw serve` path
+- `bw serve` mode requires `BW_HOST` and either API-key or user/password login
+- Keep runtime behavior non-root with `HOME=/bw`
+
+## State Handling
+
+- Persisted `/bw` is acceptable for interactive CLI use
+- Long-lived `bw serve` automation is safer with a clean or ephemeral `/bw`
+  across upgrades
+- Do not add runtime logging that exposes secrets or session material

agent-instructions/testing.md

@@ -0,0 +1,19 @@
+# Testing & Verification
+
+## Overview
+
+Use this file when validating changes in this repository.
+
+## Commands
+
+- `docker build -t bitwarden-cli-docker:local .`
+- `shellcheck entrypoint.sh`
+- `actionlint .github/workflows/build.yml`
+- `docker run --rm -v "$PWD:/usr/src/app" -w /usr/src/app \`
+  `renovate/renovate:latest renovate-config-validator`
+
+## Expectations
+
+- Validate both image buildability and workflow syntax for automation changes
+- Keep verification focused on the tracked release flow and runtime wrapper
+- Prefer operator-facing README updates when runtime expectations change