From 3993d944ba83f99201a93719c040ae775bb60a93 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C4=90=C3=A1i=20Chung=20Hy?= <daichunghy30042004@gmail.com>
Date: Sun, 23 Aug 2026 22:25:25 +0700
Subject: [PATCH] docs: clarify alpha status and adapter contributions

---
 AGENTS.md                 |  4 +++-
 README.md                 |  6 +++++-
 docs/ADAPTER_AUTHORING.md | 42 +++++++++++++++++++++++++++++++++++++++
 3 files changed, 50 insertions(+), 2 deletions(-)
 create mode 100644 docs/ADAPTER_AUTHORING.md

diff --git a/AGENTS.md b/AGENTS.md
index 5d48dec..d7d5277 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -10,7 +10,9 @@ npm run verify
 npx contribkit preflight --repo . --base HEAD
 ```
 
-The current GitHub release is `contribkit@0.1.0-alpha.6`; npm still serves alpha.3 until OTP publication completes. Do not claim the Anthropic community plugin catalog or Claude-for-OSS eligibility.
+GitHub main is `contribkit@0.1.0-alpha.7`. The npm `alpha` dist-tag currently resolves alpha.6;
+alpha.7 publication still requires npm two-factor verification. Do not claim the Anthropic community
+plugin catalog or Claude-for-OSS eligibility.
 
 ## Rules
 
diff --git a/README.md b/README.md
index b1eacda..32bb753 100644
--- a/README.md
+++ b/README.md
@@ -11,7 +11,10 @@ contribkit is a **contribution preflight** for coding agents and humans. It comp
 
 This is **not** contributor-image generation ([LizardByte/contribkit](https://github.com/LizardByte/contribkit)), not a contribution-proposal bot ([vidiyala99/contribkit](https://github.com/vidiyala99/contribkit)), and not a GitHub merge gate ([PatchGate](https://github.com/daichunghy/patchgate)).
 
-**Status:** `0.1.0-alpha.7` on GitHub main and npm alpha. Not in the Anthropic community plugin catalog. Not a Claude-for-OSS eligibility claim.
+**Status:** `0.1.0-alpha.7` on GitHub main. The npm `alpha` dist-tag currently resolves
+`0.1.0-alpha.6`; alpha.7 is prepared in source but still requires npm two-factor verification
+before publication. Not in the Anthropic community plugin catalog. Not a Claude-for-OSS eligibility
+claim.
 
 ```sh
 git clone --branch v0.1.0-alpha.7 https://github.com/daichunghy/contribkit.git
@@ -59,6 +62,7 @@ Claude Code plugin (local marketplace, not the Anthropic catalog):
 - Claude plugin: `.claude-plugin/plugin.json`, `skills/*`, `hooks/hooks.json` (Bash|PowerShell `gh`/`glab` **and** `mcp__.*__create_pull_request`)
 - MCP stdio: `node dist/src/cli.js mcp` tools `compile_contract`, `preflight_diff`, `explain_receipt`
 - Bundled adapters: `python-pytest`, `node-npm-test`, `go-test` (advisory `command_recorded` only unless `blockAdapters`)
+- Adapter authoring guide: [docs/ADAPTER_AUTHORING.md](docs/ADAPTER_AUTHORING.md)
 
 ## What is not shipped
 
diff --git a/docs/ADAPTER_AUTHORING.md b/docs/ADAPTER_AUTHORING.md
new file mode 100644
index 0000000..b9e6ce3
--- /dev/null
+++ b/docs/ADAPTER_AUTHORING.md
@@ -0,0 +1,42 @@
+# Adapter authoring
+
+Bundled adapters add repository-specific test commands to the compiled contribution contract. They
+are deliberately small data files: the hot path remains deterministic and does not execute a target
+repository unless the caller opts into `--run-tests`.
+
+## Manifest
+
+Create `adapters/<id>/adapter.json`:
+
+```json
+{
+  "id": "python-pytest",
+  "match": { "filesAny": ["pyproject.toml", "pytest.ini", "tests"] },
+  "testCommand": "pytest",
+  "maxDiffLines": null
+}
+```
+
+The `id` must equal the directory name. `match.filesAny` is a non-empty list of repository paths;
+`testCommand` must be one of the existing command shapes accepted by `src/allowlist.ts`. An adapter
+with an unknown command is reported as `needs-human` and is never executed. `maxDiffLines` is
+reserved for the contract rule that evaluates patch size; use `null` when the adapter has no limit.
+
+Add a short `README.md` and, when the command needs repository-specific guidance, a `hints.yml` file.
+Do not put credentials, network calls, shell pipelines, command substitution, or model instructions
+in an adapter.
+
+## Verification and pull requests
+
+```sh
+npm run verify
+node dist/src/cli.js compile --repo . --base HEAD --json
+```
+
+An adapter PR should include one positive fixture and one negative or unsupported-command case. The
+PR description must state whether the adapter is advisory or listed in `blockAdapters`; the default
+is advisory so a new ecosystem adapter cannot silently block a contribution. Keep the command
+recorded in the receipt and let the maintainer decide whether it belongs in a blocking policy.
+
+The current bundled set is `python-pytest`, `node-npm-test`, and `go-test`. New adapters should have
+a real repository shape to match and should not be added only to increase the adapter count.