diff --git a/.github/workflows/test.yaml b/.github/workflows/test.yaml
index 8d00f7c..8b9af20 100644
--- a/.github/workflows/test.yaml
+++ b/.github/workflows/test.yaml
@@ -1,18 +1,54 @@
-name: Run 
+name: Smoke tests
 
 on:
-  workflow_dispatch: 
-    inputs:
-      command:
-        description: "Command to execute"
-        required: true
-        default: "ansible-playbook"
-
-jobs: 
-  run: 
+  push:
+    branches: ["**"]
+  pull_request:
+    branches: ["master"]
+  workflow_dispatch:
+
+jobs:
+  smoke:
     runs-on: ubuntu-latest
-    steps: 
-      - uses: eftechcombr/ansible-cli-github-action@master
-        with:
-          command: "ansible --version"
-    
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build Docker image
+        run: docker build -t ansible-cli-smoke:test .
+
+      - name: smoke_build — image built
+        run: docker image inspect ansible-cli-smoke:test > /dev/null
+
+      - name: smoke_ansible — CLI version checks
+        run: |
+          docker run --rm ansible-cli-smoke:test "ansible --version"
+          docker run --rm ansible-cli-smoke:test "ansible-playbook --version"
+          docker run --rm ansible-cli-smoke:test "ansible-inventory --help"
+
+      - name: smoke_python — dependency imports
+        run: |
+          docker run --rm ansible-cli-smoke:test "python -c 'import winrm; print(\"winrm ok\")'"
+          docker run --rm ansible-cli-smoke:test "python -c 'import ansible; print(\"ansible ok\")'"
+
+      - name: smoke_shell — eval passthrough
+        run: |
+          OUTPUT=$(docker run --rm ansible-cli-smoke:test "echo hello from ansible")
+          [ "$OUTPUT" = "hello from ansible" ] || { echo "FAIL: $OUTPUT"; exit 1; }
+
+      - name: smoke_shell — exit code propagation
+        run: |
+          set +e
+          docker run --rm ansible-cli-smoke:test "exit 42"
+          RC=$?
+          set -e
+          [ "$RC" -eq 42 ] || { echo "FAIL: expected 42, got $RC"; exit 1; }
+
+      - name: smoke_playbook — syntax check
+        run: |
+          docker run --rm -v ${{ github.workspace }}/tests:/tests:ro ansible-cli-smoke:test \
+            "ansible-playbook --syntax-check /tests/test.yml"
+
+      - name: smoke_playbook — ping localhost
+        run: |
+          docker run --rm -v ${{ github.workspace }}/tests:/tests:ro ansible-cli-smoke:test \
+            "ansible-playbook -i 'localhost,' -c local /tests/test.yml"
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..87f18a4
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,30 @@
+# AGENTS.md
+
+## Dev environment tips
+- Build the Docker image with `docker build -t ansible-cli-smoke:test .` before running tests.
+- Use `docker compose build` for the Compose-based build.
+
+## Testing instructions
+- Run all smoke tests: `tests/smoke_build.sh && tests/smoke_ansible.sh && tests/smoke_python.sh && tests/smoke_shell.sh && tests/smoke_playbook.sh`
+- Or run individual tests: `tests/smoke_build.sh` (must run first — sets image tag), then any of `tests/smoke_ansible.sh`, `tests/smoke_python.sh`, `tests/smoke_shell.sh`, `tests/smoke_playbook.sh`
+- CI runs all smoke tests via `.github/workflows/test.yaml` on every push and PR.
+
+## PR instructions
+- Follow Conventional Commits (for example, `feat(scaffolding): add doc links`).
+- Cross-link new scaffolds in `docs/README.md` and `agents/README.md` so future agents can find them.
+- Attach sample CLI output or generated markdown when behaviour shifts.
+- Confirm the built artefacts in `dist/` match the new source changes.
+
+## Repository map
+- `action.yml` — GitHub Action metadata (inputs, branding, Docker runtime config)
+- `docker-compose.yaml` — local dev convenience for building and tagging the image
+- `Dockerfile` — builds the container from `python:3.11-slim`
+- `entrypoint.sh` — container entrypoint, executes `eval $1`
+- `README.md` — user-facing documentation
+- `requirements.txt` — Python dependencies (`ansible`, `pywinrm[credssp]`)
+- `tests/` — smoke test scripts and test fixtures
+
+## AI Context References
+- Documentation index: `.context/docs/README.md`
+- Agent playbooks: `.context/agents/README.md`
+- Contributor guide: `CONTRIBUTING.md`
diff --git a/tests/smoke_ansible.sh b/tests/smoke_ansible.sh
new file mode 100755
index 0000000..a7d4ea3
--- /dev/null
+++ b/tests/smoke_ansible.sh
@@ -0,0 +1,17 @@
+#!/bin/sh
+set -e
+
+. /tmp/ansible_smoke_image 2>/dev/null || IMG_LABEL="ansible-cli-smoke:test"
+
+echo "=== smoke_ansible: Ansible CLI tools ==="
+
+echo "  -> ansible --version"
+docker run --rm "$IMG_LABEL" "ansible --version"
+
+echo "  -> ansible-playbook --version"
+docker run --rm "$IMG_LABEL" "ansible-playbook --version"
+
+echo "  -> ansible-inventory --help"
+docker run --rm "$IMG_LABEL" "ansible-inventory --help"
+
+echo "PASS: smoke_ansible"
diff --git a/tests/smoke_build.sh b/tests/smoke_build.sh
new file mode 100755
index 0000000..abff463
--- /dev/null
+++ b/tests/smoke_build.sh
@@ -0,0 +1,11 @@
+#!/bin/sh
+set -e
+
+echo "=== smoke_build: Docker image build ==="
+
+IMG_LABEL="ansible-cli-smoke:test"
+
+docker build -t "$IMG_LABEL" .
+
+echo "PASS: smoke_build"
+echo "IMG_LABEL=$IMG_LABEL" > /tmp/ansible_smoke_image
diff --git a/tests/smoke_playbook.sh b/tests/smoke_playbook.sh
new file mode 100755
index 0000000..9ba6703
--- /dev/null
+++ b/tests/smoke_playbook.sh
@@ -0,0 +1,17 @@
+#!/bin/sh
+set -e
+
+. /tmp/ansible_smoke_image 2>/dev/null || IMG_LABEL="ansible-cli-smoke:test"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+echo "=== smoke_playbook: Ansible playbook parsing and local run ==="
+
+echo "  -> syntax check"
+docker run --rm -v "$SCRIPT_DIR:/tests:ro" "$IMG_LABEL" \
+  "ansible-playbook --syntax-check /tests/test.yml"
+
+echo "  -> ping localhost"
+docker run --rm -v "$SCRIPT_DIR:/tests:ro" "$IMG_LABEL" \
+  "ansible-playbook -i 'localhost,' -c local /tests/test.yml"
+
+echo "PASS: smoke_playbook"
diff --git a/tests/smoke_python.sh b/tests/smoke_python.sh
new file mode 100755
index 0000000..63afb66
--- /dev/null
+++ b/tests/smoke_python.sh
@@ -0,0 +1,14 @@
+#!/bin/sh
+set -e
+
+. /tmp/ansible_smoke_image 2>/dev/null || IMG_LABEL="ansible-cli-smoke:test"
+
+echo "=== smoke_python: Python dependency imports ==="
+
+echo "  -> import winrm"
+docker run --rm "$IMG_LABEL" "python -c \"import winrm; print('winrm version:', winrm.__version__)\""
+
+echo "  -> import ansible"
+docker run --rm "$IMG_LABEL" "python -c \"import ansible; print('ansible loaded ok')\""
+
+echo "PASS: smoke_python"
diff --git a/tests/smoke_shell.sh b/tests/smoke_shell.sh
new file mode 100755
index 0000000..a6ef121
--- /dev/null
+++ b/tests/smoke_shell.sh
@@ -0,0 +1,21 @@
+#!/bin/sh
+set -e
+
+. /tmp/ansible_smoke_image 2>/dev/null || IMG_LABEL="ansible-cli-smoke:test"
+
+echo "=== smoke_shell: eval passthrough + exit codes ==="
+
+echo "  -> echo passthrough"
+OUTPUT=$(docker run --rm "$IMG_LABEL" "echo hello from ansible")
+echo "       output: $OUTPUT"
+[ "$OUTPUT" = "hello from ansible" ] || { echo "FAIL: unexpected output"; exit 1; }
+
+echo "  -> exit code propagation (expect exit 42)"
+set +e
+docker run --rm "$IMG_LABEL" "exit 42"
+RC=$?
+set -e
+echo "       exit code: $RC"
+[ "$RC" -eq 42 ] || { echo "FAIL: expected 42, got $RC"; exit 1; }
+
+echo "PASS: smoke_shell"
diff --git a/tests/test.yml b/tests/test.yml
new file mode 100644
index 0000000..232ac4f
--- /dev/null
+++ b/tests/test.yml
@@ -0,0 +1,7 @@
+---
+- name: Smoke test connectivity
+  hosts: localhost
+  gather_facts: false
+  tasks:
+    - name: Verify reachability
+      ping: