From 6eeb2a451bb02e1d3cdc02d39fa720643d1c4885 Mon Sep 17 00:00:00 2001
From: Daniel <danoonyl@gmail.com>
Date: Fri, 18 Sep 2026 23:05:58 +0800
Subject: [PATCH] docs: add contributing, changelog, and playwright setup note

---
 CHANGELOG.md    | 15 +++++++++++++
 CONTRIBUTING.md | 60 +++++++++++++++++++++++++++++++++++++++++++++++++
 README.md       |  4 ++++
 3 files changed, 79 insertions(+)
 create mode 100644 CHANGELOG.md
 create mode 100644 CONTRIBUTING.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..e539e9a
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,15 @@
+# Changelog
+
+All notable changes to Agent Action Stack are recorded here. The format
+follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this
+project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+### Added
+- `CONTRIBUTING.md` describing cross-repo coordination and the
+  `stack-lock.json` policy.
+- `CHANGELOG.md` (this file).
+- Playwright setup note in the Quick start section of `README.md`.
+
+[Unreleased]: https://github.com/EauDoon/agent-action-stack/compare/main...HEAD
\ No newline at end of file
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..735a483
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,60 @@
+# Contributing
+
+Agent Action Stack is a thin orchestrator wrapping three sibling repositories:
+
+- [constitutional-agent-testbench](https://github.com/EauDoon/constitutional-agent-testbench) (decide)
+- [consequence-rail](https://github.com/EauDoon/consequence-rail) (act)
+- [mandatebound](https://github.com/EauDoon/mandatebound) (prove)
+
+All behavior lives in those libraries. This repo only sequences them and
+records run bundles. Contributions here should preserve that boundary.
+
+## Cross-repo coordination
+
+`stack-lock.json` (schema `agent-action-stack.lock/v1`) pins each sibling to
+one reviewed commit plus its expected entrypoints. `npm run bootstrap` checks
+out those exact commits, rejects substituted or dirty pre-existing
+directories, runs `npm ci --ignore-scripts` where declared, and runs each
+component's explicit build command.
+
+Changing a pinned component is a coordinated change:
+
+1. Land the upstream change in the sibling repo first.
+2. Bump the matching `commit` in `stack-lock.json` here.
+3. Update `expected_entrypoints`, `post_build_entrypoints`, `install`, or
+   `build` only if the sibling's published contract actually changed.
+4. Run `npm run integration` to prove the new pin still composes from a clean
+   checkout.
+
+Do not bypass the lockfile. Editing `deps/` directly, swapping a remote URL,
+or relaxing the dirty-checkout rejection are all out of scope for normal
+contributions.
+
+## Pull requests
+
+- One branch, one focused change.
+- Branch names: `imp/<short-topic>-<date>`.
+- Ship via a pull request; do not push to `main` directly.
+- Keep the orchestrator thin. If a change adds real behavior, it usually
+  belongs in one of the three sibling repos, not here.
+
+## Local checks
+
+```bash
+npm test
+npm run integration
+npm run example:review-handoff
+```
+
+`npm run test:browser` requires Playwright Chromium:
+
+```bash
+npx playwright install chromium
+npm run test:browser
+```
+
+## What not to contribute here
+
+- Real connectors, real secrets, real payment or merchant integrations.
+- Changes that would read or write private repositories.
+- Policy or rail rules that should live in their owning library.
\ No newline at end of file
diff --git a/README.md b/README.md
index 2f8c276..c8a7929 100644
--- a/README.md
+++ b/README.md
@@ -36,6 +36,10 @@ npm run bootstrap
 npm run demo
 ```
 
+Optional, only for the browser test suite: Playwright needs a Chromium
+binary. After `npm install`, run `npx playwright install chromium` once
+before `npm run test:browser`.
+
 Expected human output (pass path, no fault):
 
 ```text