git-a2a 1.0.1 → 1.1.0-rc.2

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "git-a2a",
-  "version": "1.0.1",
+  "version": "1.1.0-rc.2",
   "description": "Import git modules together with their owning agents",
+  "mcpName": "io.github.neprel/git-a2a",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -13,12 +14,16 @@
   "engines": {
     "node": ">=18"
   },
+  "files": [
+    "bin/",
+    "skills/"
+  ],
   "optionalDependencies": {
-    "@git-a2a/darwin-amd64": "1.0.1",
-    "@git-a2a/darwin-arm64": "1.0.1",
-    "@git-a2a/linux-amd64": "1.0.1",
-    "@git-a2a/linux-arm64": "1.0.1",
-    "@git-a2a/windows-amd64": "1.0.1",
-    "@git-a2a/windows-arm64": "1.0.1"
+    "@git-a2a/darwin-amd64": "1.1.0-rc.2",
+    "@git-a2a/darwin-arm64": "1.1.0-rc.2",
+    "@git-a2a/linux-amd64": "1.1.0-rc.2",
+    "@git-a2a/linux-arm64": "1.1.0-rc.2",
+    "@git-a2a/windows-amd64": "1.1.0-rc.2",
+    "@git-a2a/windows-arm64": "1.1.0-rc.2"
   }
 }

package/skills/git-a2a/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: git-a2a
+description: Use git-a2a to consume or author a dependency on a Git repository together with its owner, resolve who owns a dependency, inspect or repair an AGENTS.md module roster, or edit and validate a2amodule.yml manifest.
+compatibility: requires git ≥ 2.25 and the git-a2a CLI
+metadata:
+  version: "1.1.0"
+---
+
+# git-a2a
+
+Use the repository's `a2amodule.yml` and `a2amodule.lock` as durable truth. Treat
+`.git-a2a/cache` as disposable. Never read dependency internals: read its published surface and
+contact its declared owner for anything else.
+
+Start with `git-a2a usage`. Use `--json` on read commands when structured output is useful.
+
+## Consume a module
+
+1. Run `git-a2a doctor` and inspect the current `git-a2a status -v`.
+2. Add the owner's Git URL with `git-a2a add URL`; one resolved commit must drive every ecosystem.
+3. Run `git-a2a sync` to opt into the managed AGENTS.md roster.
+4. Inspect public knowledge with `git-a2a show ID --surface`.
+5. Before committing, run `git-a2a status`, the repository tests, and review the manifest, lock,
+   package-manager files, and AGENTS.md together.
+
+After a fresh clone, run `git-a2a fetch` to reconstruct cache from the lock. Do not use `update`
+just to prime cache, and never commit `.git-a2a/`.
+
+Read [the CLI reference](references/cli.md) when choosing flags for add, set, pin, unpin, wire,
+update, remove, fetch, show, or sync.
+
+## Author a module
+
+1. Run `git-a2a init --id ID --yes`.
+2. Describe module identity, native exports, the deliberately public surface, agents, contacts,
+   routing policy, consumer boundary, and release channel.
+3. Validate with `git-a2a validate` and canonicalize with `git-a2a fmt --check`.
+4. Export cards with `git-a2a card export AGENT` and the catalog with
+   `git-a2a catalog export` when publishing discovery metadata.
+
+Read [the authoring guide](references/authoring.md) for the workflow and
+[the manifest field reference](references/manifest-reference.md) for exact values and
+consequences. Do not guess an open-vocabulary token's behavior.
+
+## Check health or change a dependency
+
+- `git-a2a fetch`: restore cache at locked commits without changing durable state.
+- `git-a2a status --offline`: verify cache, wiring, cards/trust, and roster without network.
+- `git-a2a update --check`: report upstream movement; exit 1 means an update exists.
+- `git-a2a update`: move the lock and every supported ecosystem together.
+- `git-a2a set ID --ref REF`: deliberately change source/ref policy.
+- `git-a2a pin ID` / `git-a2a unpin ID --ref REF`: freeze or resume tracking.
+- `git-a2a wire ID`: repair native dependency entries from manifest and lock.
+
+Do not hand-edit a managed AGENTS.md block. Run `git-a2a sync`, or let a successful dependency
+mutation refresh an existing block.
+
+## Contact an owner
+
+1. Resolve the declared route with `git-a2a who ID --intent INTENT [--path FILE]`.
+2. Read the owner's contact note and consumer policy.
+3. With authorization for the external side effect, put a concise request in a file and run
+   `git-a2a contact ID --intent INTENT --message FILE`.
+
+`contact` may create an A2A task or GitHub Issue. URL, email, and chat kinds print instructions;
+do not invent delivery or store conversation state.
+
+## Outcomes
+
+- Exit 0: action completed or check is clean.
+- Exit 1: drift/failure was found or an operational action failed.
+- Exit 2: invalid input, absent subject, unknown identity, or nothing resolved.
+
+If a command fails, preserve the user's files and report its decisive stderr line. Mutating
+commands are transactional; do not manually complete a partial-looking operation without first
+checking `git diff`, `git-a2a validate`, and `git-a2a status -v`.

package/skills/git-a2a/references/authoring.md

@@ -0,0 +1,154 @@
+# Authoring an a2amodule
+
+This guide is for the owner of a repository that other agents or projects should consume. The
+[field reference](manifest-reference.md) is the exact lookup for types and defaults; this page is
+the sequence for making a useful contract. The public
+[`acme-lib-utils`](https://github.com/neprel/git-a2a-demo-acme-lib) repository is the worked
+example throughout.
+
+## 1. Start at the repository boundary
+
+Run `init` in the repository root, or in the module directory inside a monorepo:
+
+```sh
+git-a2a init --id acme-lib-utils \
+  --description "Shared formatting utilities. Ask about the cross-language contract." \
+  --surface surface/
+```
+
+`module.id` is the stable consumer identity and lock key. Keep it short, lowercase, and stable;
+renaming it breaks references. Add `module.repository` as the owner-declared canonical Git URL.
+It is provenance, not an implicit fetch redirect. If the module later moves, leave
+`module.moved-to` at the old source so `update` can report the destination without silently
+following it.
+
+Declare `module.release.channel` when consumers should follow a branch such as `main`; otherwise
+an add with no ref follows the remote default branch. Set `release.tags: true` only when the
+repository really publishes semantic-version tags. The declaration does not create releases.
+
+## 2. Declare every importable export
+
+An export says how the same Git revision appears to a native ecosystem. Its `name` is the value
+that ecosystem imports, not necessarily the repository or module id.
+
+| Ecosystem | `name` means | Typical native file |
+| --- | --- | --- |
+| `npm` | package name, including scope | `package.json` |
+| `pypi` | PEP 503 distribution name | `pyproject.toml` |
+| `golang` | Go module import path | `go.mod` |
+| `cargo` | crate name | `Cargo.toml` |
+| `swift` | SwiftPM package identity | `Package.swift` |
+| `pub` | Dart package name | `pubspec.yaml` |
+| `gem` | gem name | `Gemfile` |
+| `composer` | Composer `vendor/package` | `composer.json` |
+| `hex` | Hex package name | `mix.exs` |
+| `hackage` | Cabal package name | `*.cabal` or `stack.yaml` |
+| `zig` | dependency name | `build.zig.zon` |
+| `clojure` | deps.edn symbol | `deps.edn` |
+| `nix` | flake input name | `flake.nix` |
+
+Use `path` when that package lives below the module directory. An ecosystem that cannot express
+the Git URL, ref mode, or subdirectory is reported as `not wired`; never claim an import that the
+native tool cannot reproduce. The demo library declares npm, PyPI, and Go exports for one API:
+
+```yaml
+exports:
+  - { ecosystem: npm, name: "@acme/lib-utils" }
+  - { ecosystem: pypi, name: acme-lib-utils }
+  - { ecosystem: golang, name: github.com/neprel/git-a2a-demo-acme-lib }
+```
+
+## 3. Publish a surface, not the implementation
+
+`module.surface` is the directory consumers may read in addition to the manifest. Put stable API
+signatures, behavior, limits, compatibility notes, and small usage examples there. Do not publish
+internal plans, private prompts, credentials, memories, or implementation instructions.
+
+The boundary is ask-not-read: if an answer is not in the surface, the consumer contacts an owner.
+The demo's `surface/API.md` states the shared function contract and `surface/NOTES.md` states
+cross-language facts. `git-a2a show acme-lib-utils --surface` materializes that declared content
+without granting access to the rest of the dependency repository.
+
+## 4. Bind agents and cards
+
+Each agent binding needs a stable `name` and a `role`; `scope` defaults to `**`. A more specific
+matching scope wins before manifest order. Core roles are `owner`, `maintainer`, `spec`,
+`reviewer`, and `support`, but roles remain an open vocabulary.
+
+`card` may be a live A2A v1.0 URL or a repository-relative static JSON file. The card is the
+agent's self-description; do not copy its skills, interfaces, or security into the manifest.
+Use binding `description` only for repository-specific context or when no card exists. A static
+card may demonstrate discovery without running an agent service, but its description must say so.
+
+With `trust.signatures: true`, the card must carry a valid detached JWS over its RFC 8785
+canonical form. `status` fails for unsigned or invalid cards; `update` retains code changes and
+prints a trust warning. Use `git-a2a card verify FILE_OR_URL` before enabling the requirement.
+
+## 5. Add contacts by intent
+
+Contacts are ordered. Every contact declares one or more request `intents` and a `kind`. Core
+intents are `question`, `change`, `bug`, `review`, and `incident`; both intents and kinds remain
+open vocabularies. `"*"` is the fallback for an otherwise unmatched intent.
+
+```yaml
+agents:
+  - name: acme-pm
+    role: spec
+    scope: [surface/**, a2amodule.yml]
+    card: https://git-a2a.com/demo/agents/acme-pm/.well-known/agent-card.json
+    contacts:
+      - intents: [change]
+        kind: github-issue
+        repo: neprel/git-a2a-demo-acme-lib
+        labels: [change-request, from-agent]
+        note: Describe the consumer, the need, and the affected languages.
+```
+
+`a2a` and `github-issue` have delivery drivers. `url`, `email`, and chat kinds print an exact
+instruction; they do not pretend delivery occurred. The kind-specific keys and delivery behavior
+are listed in the [field reference](manifest-reference.md).
+
+## 6. State routing and the consumer boundary
+
+`policy.intents` maps an intent to a role. Unlisted intents route to `owner`. In the demo,
+`change: spec` sends contract requests to `acme-pm`, while bugs stay with the owner.
+
+`policy.consumers.may` and `may-not` are open-vocabulary declarations rendered into the managed
+AGENTS.md roster. They tell an agent what the owner permits; git-a2a is not an authorization
+service. A useful library boundary is:
+
+```yaml
+policy:
+  intents: { change: spec }
+  consumers:
+    may: [read-surface, ask, open-issue, propose-change]
+    may-not: [commit, edit-spec, release]
+```
+
+## 7. Validate and publish projections
+
+Before committing, run:
+
+```sh
+git-a2a fmt a2amodule.yml
+git-a2a validate a2amodule.yml
+git-a2a card export acme-lib-utils --out acme-lib-utils.agent-card.json
+git-a2a card validate acme-lib-utils.agent-card.json
+git-a2a catalog export --out ai-catalog.json
+git-a2a status -v
+```
+
+Review the formatted manifest and generated projections, then commit the manifest, surface, and
+any intentionally static cards/catalog. Do not commit `.git-a2a/`; it is disposable local cache.
+The owner publishes the Git ref and any card URLs through its normal release and hosting process.
+
+## 8. What the consumer receives
+
+A consumer runs `git-a2a add URL` and gets one resolved commit in `a2amodule.lock`, native package
+entries for every applicable export, card snapshots in ignored local state, and the published
+surface on demand. `git-a2a sync` writes a bounded roster into AGENTS.md containing the module
+description, consumer policy, routed owners, and declared contacts. It never imports dependency
+instructions or code.
+
+Clone the [public consumer](https://github.com/neprel/git-a2a-demo-acme-app), then run `status`,
+`who`, `show --surface`, and `update --check` to see the authored contract from the other side.

package/skills/git-a2a/references/cli.md

@@ -0,0 +1,403 @@
+# git-a2a command reference
+
+Every command accepts the global `--timeout DURATION` option (default `120s`) and `--yes` as a
+non-interactive no-op for automation. No command prompts for input. Requested data is written to
+stdout; verdicts and advisories go to stderr. Exit `0` means success, `1` means a
+completed check found drift/failure, and `2` means invalid input or nothing resolved.
+The repository's `.hint` sources and the commands used to read them are explained in
+[Specification as source (HINT)](../README.md#specification-as-source-hint).
+
+## init
+
+`git-a2a init [--id ID] [--description TEXT] [--surface DIR] [--export ECOSYSTEM=NAME]
+[--example lib|app] [--yes]`
+creates `a2amodule.yml` and adds `.git-a2a/` to `.gitignore`. Repeat `--export`; `--yes` is an
+accepted no-op for automation. `--example lib|app` writes a complete, commented owner or
+consumer manifest; it may be combined with `--id`, but not the other content flags. Exit `1` if
+a manifest already exists; invalid combinations exit `2`.
+
+```text
+$ git-a2a init --id acme-app --yes
+initialized module acme-app
+```
+
+```text
+$ git-a2a init --example lib --id acme-lib
+initialized lib example module acme-lib
+```
+
+## validate
+
+`git-a2a validate [FILE ...] [--json]` validates manifests and locks; without paths it checks the
+files in the current module. `--json` emits one structured result per requested file, including
+validation errors. Invalid files exit `1`; an empty subject set exits `2`.
+
+```text
+$ git-a2a validate
+a2amodule.yml: valid
+1 file(s): valid
+```
+
+## add
+
+`git-a2a add URL [--id ID] [--path DIR] [--track locked|floating] [--wire LIST|--no-wire]
+[--no-refresh]`
+fetches the remote manifest, resolves one commit, wires detected ecosystems, writes the lock,
+and snapshots cards. `--no-refresh` edits project manifests but skips package-manager Refresh.
+Missing optional toolchains warn but do not prevent the manifest edit.
+Exit `1` covers fetch/wiring failure and `2` invalid arguments.
+
+```text
+$ git-a2a add https://github.com/acme/lib.git --wire npm,golang
+added acme-lib at ea1e8656ad1e6eaeef81759c10969e64defdd9ce
+```
+
+## set
+
+`git-a2a set ID [--git URL] [--ref REF] [--path DIR] [--track locked|floating] [--id NEW-ID]
+[--dry-run] [--no-refresh]` transactionally changes a dependency source or identity and rewires
+it. `--no-refresh` skips package-manager Refresh. Exit `1`
+means the transaction failed and rolled back; exit `2` means the ID/options did not resolve.
+
+```text
+$ git-a2a set acme-lib --ref release/1.x --dry-run
+would set acme-lib to ref release/1.x
+```
+
+## pin
+
+`git-a2a pin ID [COMMIT] [--no-refresh]` changes the dependency ref to a full 40-character
+commit. Without `COMMIT`, the currently locked commit is used. `--no-refresh` skips
+package-manager Refresh. Exit `1` means lock/rewiring failure; exit `2`
+means an unknown ID or invalid SHA.
+
+```text
+$ git-a2a pin acme-lib
+set acme-lib to https://github.com/acme/lib.git at ea1e8656ad1e6eaeef81759c10969e64defdd9ce
+```
+
+## unpin
+
+`git-a2a unpin ID --ref REF [--track locked|floating] [--no-refresh]` returns a pinned dependency
+to a branch or tag and resolves it immediately. `--no-refresh` skips package-manager Refresh.
+Exit `1` means the transaction failed; exit `2` means the arguments or dependency were invalid.
+
+```text
+$ git-a2a unpin acme-lib --ref main
+set acme-lib to https://github.com/acme/lib.git at ea1e8656ad1e6eaeef81759c10969e64defdd9ce
+```
+
+## wire
+
+`git-a2a wire [ID] [--ecosystem NAME] [--no-refresh]` reapplies declared exports to detected
+project files. With `--ecosystem`, that adapter is mandatory; `--no-refresh` skips its
+package-manager Refresh. Invalid/missing subjects exit `2`; a required adapter failure exits `1`.
+
+```text
+$ git-a2a wire acme-lib --ecosystem npm
+npm: wired acme-lib
+```
+
+## update
+
+`git-a2a update [ID ...] [--check] [--review|--no-review] [--follow-moves] [--no-refresh]`
+resolves upstream refs and transactionally updates changed dependencies. `--check` only reports
+availability; `--review` prints manifest/surface diffs; `--no-refresh` skips package-manager
+Refresh; moves require explicit `--follow-moves`. Exit `1`
+means updates exist in check mode or an update failed; exit `2` means no dependency resolved.
+
+```text
+$ git-a2a update --check
+acme-lib: ea1e8656ad1e -> 3ad806dc575c
+1 dependency update(s) available
+```
+
+## remove
+
+`git-a2a remove ID [--keep-wiring]` removes the manifest/lock/cache entry and normally unwires
+all owned package-manager entries. Exit `1` means removal failed; exit `2` means the ID/options
+did not resolve.
+
+After any successful `add`, `update`, `set`, `pin`, `unpin`, `wire`, or `remove`, an existing
+`AGENTS.md` managed block is rendered again as the final mutation. These commands never create a
+new block; use `sync` once to opt in.
+
+```text
+$ git-a2a remove acme-lib
+removed acme-lib (cache deleted; it can be recreated by add)
+```
+
+## fetch
+
+`git-a2a fetch [ID ...] [--surface] [--json]` restores disposable
+`.git-a2a/cache` content from the exact commits and hashes in `a2amodule.lock`. Without IDs it
+fetches every dependency; `--surface` also restores a declared surface whose tree hash is already
+recorded in the lock. It never resolves a moving ref and never changes the manifest, lock, or
+package-manager files. Missing/incomplete lock entries and hash mismatches exit `1`; invalid
+options or an empty dependency set exit `2`.
+
+```text
+$ git-a2a fetch --json
+[{"id":"acme-lib","commit":"ea1e8656ad1e6eaeef81759c10969e64defdd9ce","manifest":"sha256:…","method":"sparse"}]
+```
+
+## show
+
+`git-a2a show [ID] [--json] [--surface]` prints the own or cached dependency manifest. With
+`--surface`, it materialises and lists the published surface before showing it. Exit `2` means
+the module or surface was not resolvable.
+
+```text
+$ git-a2a show acme-lib --surface
+surface/API.md
+schema: 1
+```
+
+## sync
+
+`git-a2a sync [--check] [--brief] [--target FILE]` renders the dependency/owner roster into
+`AGENTS.md` and repeated targets. `--check` exits `1` without writing when blocks are stale.
+
+```text
+$ git-a2a sync
+AGENTS.md
+updated 1 managed block(s)
+```
+
+## who
+
+`git-a2a who [ID] [--intent INTENT] [--path FILE] [--json]` applies intent → role → scoped
+agent → contact routing. No match exits `2`.
+
+```text
+$ git-a2a who acme-lib --intent change
+acme-lib change → owner → library-owner
+```
+
+## contact
+
+`git-a2a contact ID --intent INTENT --message FILE|- [--wait]` uses the first supported routed
+contact. A2A sends `SendMessage`; GitHub Issue uses `gh` then REST; URL/email/chat contacts print
+instructions. Each delivery writes one record and stores no conversation state. `ask` is an
+alias. Exit `1` means delivery failed; exit `2` means routing/input resolved nothing.
+
+```text
+$ printf 'Please review the API.' | git-a2a contact acme-lib --intent review --message -
+acme-lib owner github-issue issue=https://github.com/acme/lib/issues/42
+```
+
+## status
+
+`git-a2a status [ID ...] [--offline] [--json] [-v]` checks upstream, manifest/cache hashes,
+wiring, cards/trust, and rendered blocks. The table contains dependencies only; the consuming
+module is summarized below it. A repository that has not run `sync` has roster/SYNC `none`, which
+is healthy; `stale` means an existing managed block differs. `-v` adds own-module findings,
+prerequisite state, and adapter verification labels. Any unhealthy dependency or own-module
+check exits `1`; no match exits `2`.
+
+```text
+$ git-a2a status --offline
+acme-lib  canonical  branch main  unknown  clean  npm clean  unknown  none
+consumer-app: manifest valid · agents none · roster none
+1 dependency: clean
+```
+
+## card
+
+`git-a2a card <export|validate|verify|show> [options]` manages native A2A cards:
+`card export AGENT [--out FILE]`, `card validate FILE|URL`, `card verify FILE|URL`, and
+`card show [ID] [AGENT] [--json]`. Unresolvable input exits `2`; invalid content/signature exits
+`1`.
+
+```text
+$ git-a2a card verify ./owner-card.json
+./owner-card.json: verified EdDSA signature with key production
+card signature verified
+```
+
+## catalog
+
+`git-a2a catalog export [--out FILE]` emits an ARD 1.0 `ai-catalog.json` whose entries reference
+or embed the module's A2A cards. Exit `1` means encoding/writing failed; exit `2` means no valid
+module or agents resolved.
+
+```text
+$ git-a2a catalog export --out ai-catalog.json
+exported 2 A2A catalog entrie(s)
+```
+
+## agent
+
+`git-a2a agent add NAME --role ROLE [--scope GLOB]... [--card URL] [--contact FIELDS]...
+[--yes]` adds an agent binding. Each contact is comma-separated `key=value`; list values such as
+`intents` and `labels` use `|`, for example
+`intents=question|change,kind=github-issue,repo=acme/lib,labels=from-agent|change-request`.
+`git-a2a agent remove NAME [--yes]` removes it. `git-a2a agent list [--json] [--yes]` returns
+agents in stable name order. Mutations preserve comments, key order, extension keys, and
+flow/block style of untouched YAML nodes, validate, write atomically, then update an existing
+AGENTS.md managed block. Invalid fields exit `2`; validation/write failures and
+duplicates exit `1`; an unknown removal or empty list exits `2`.
+
+```text
+$ git-a2a agent add acme-lib-owner --role owner --scope '**' --contact 'intents=question|change,kind=github-issue,repo=acme/lib'
+added agent acme-lib-owner
+$ git-a2a agent list
+acme-lib-owner  owner  **  1 contact(s)
+1 agent(s)
+```
+
+## export
+
+`git-a2a export add ECOSYSTEM NAME [--path PATH] [--yes]` adds a native export to the current
+module. The result is validated and written atomically; relative path and duplicate violations
+exit `1`, while invalid arguments exit `2`.
+
+```text
+$ git-a2a export add npm @acme/lib --path packages/js
+added npm export @acme/lib
+```
+
+## policy
+
+`git-a2a policy set [INTENT=ROLE ...] [--may LIST] [--may-not LIST] [--notes TEXT] [--yes]`
+creates or updates intent routing and, when supplied, replaces the comma-separated consumer
+permission lists or policy notes. Omitted fields and every unrelated YAML node remain untouched.
+Invalid mappings exit `2`; validation/write failures exit `1`.
+
+```text
+$ git-a2a policy set question=owner change=spec --may read-surface,ask --may-not commit
+updated policy (2 intent mapping(s))
+```
+
+## explain
+
+`git-a2a explain PATH [--json] [--yes]` prints the generated reference entry embedded in this
+binary. Array markers may be omitted, so `agents.contacts.kind` resolves to
+`agents[].contacts[].kind`. It performs no repository or network access. Unknown paths and
+invalid arguments exit `2`.
+
+```text
+$ git-a2a explain module.id
+```
+
+```markdown
+## `module.id`
+- Type: string; required.
+…
+```
+
+## fmt
+
+`git-a2a fmt [--check] [PATH...]` canonicalises manifest/lock files or every matching file under
+a supplied directory. `--check` exits `1` without writing when formatting differs.
+
+```text
+$ git-a2a fmt spec/examples
+formatted 3 file(s)
+```
+
+## doctor
+
+`git-a2a doctor [--json]` reports Git and every toolchain required by detected ecosystems and
+wired dependencies, including version, PATH status, and platform installation hints. It never
+installs anything. Missing required Refresh tools exit `1`.
+
+```text
+$ git-a2a doctor
+git       2.51.0  found
+npm       11.5.2  found
+2 prerequisite(s): ready
+```
+
+## usage
+
+`git-a2a usage [--prompt] [--json]` prints a deterministic briefing for coding agents. The
+default is at most 60 lines and contains eight task commands with examples, exit-code meanings,
+structured-output guidance, and the manifest-reference location. `--prompt` adds the full
+fresh-agent workflow; `--json` emits the selected briefing as an ordered line array. Invalid
+options exit `2`.
+
+```text
+$ git-a2a usage
+git-a2a imports Git modules together with the agents that own them.
+Read a2amodule.yml for the module contract and a2amodule.lock for exact resolved commits.
+…
+Exit 0: request completed or check clean.
+```
+
+## setup
+
+`git-a2a setup [--check|--dry-run] [--harness LIST|--all]` detects Claude Code, Codex, Cursor,
+GitHub Copilot, Gemini CLI, OpenCode, Hermes Agent, and OpenClaw from repository markers. It
+always installs a thin skill (`SKILL.md` plus `references/README.md`) under
+`.agents/skills/git-a2a/`, also installs that thin copy under `.claude/skills/git-a2a/` when
+Claude Code is selected, and adds a bounded pointer block to `AGENTS.md`. For selected harnesses it writes only
+the project-scoped `git-a2a` MCP entry in `.mcp.json`, `.codex/config.toml`,
+`.cursor/mcp.json`, `.vscode/mcp.json`, `.gemini/settings.json`, or `opencode.json`, preserving
+unrelated configuration. It never installs or upgrades the `git-a2a` executable.
+Hermes Agent and OpenClaw only expose user-scoped MCP registries, so setup does not edit their
+home-directory files; it prints the exact `hermes mcp add` or `openclaw mcp set` command for the
+operator to run explicitly.
+
+A harness found only under the user's home directory is reported but not configured. Use
+`--harness codex,cursor` to select named harnesses even without repository markers, or `--all`
+to configure every supported repository integration. The full skill remains in the source/npm/site
+distribution; installed pointers use `git-a2a explain`, `git-a2a usage --prompt`, and the public URL.
+
+`--dry-run` prints the files that would change and exits `0`; `--check` writes nothing and exits
+`1` if any installed file or entry is missing/stale. An invalid existing config exits `1`; bad
+options exit `2`.
+
+```text
+$ git-a2a setup --dry-run
+would write .agents/skills/git-a2a/SKILL.md (cross-agent skill)
+would write AGENTS.md (skill pointer)
+setup: dry run; 5 file(s) would change
+```
+
+## mcp
+
+`git-a2a mcp [--allow-write]` runs a stateless MCP server over stdio. By default it exposes
+seven read-only tools (`who`, `show`, `status`, `validate`, `doctor`, `explain`, `usage`) plus
+the cache-restoring `fetch` tool, and
+four repository resources (`a2amodule://manifest`, `a2amodule://lock`,
+`a2amodule://roster`, `a2amodule://reference`). `--allow-write` additionally exposes `add`,
+`update`, `set`, `wire`, `sync`, and `contact`; `remove` remains CLI-only. The process opens no
+network listener and stores no server state. Protocol or command failures exit `1`; invalid
+options exit `2`.
+
+Repository-dependent tools accept an optional `root` path, defaulting to the server startup
+directory. One MCP client can use that field to work across repositories, or launch one stdio
+server per repository; instances have no listener or shared mutable server state. Fixed resources
+refer to the startup repository. `root` may name any path reachable by the process. With
+`--allow-write`, that grants mutation at any such path: the harness/host is the trust boundary.
+A future `--roots` allow-list is deliberately deferred.
+
+Run `git-a2a setup` to write project-scoped configuration for detected harnesses, including
+Claude Code's `.mcp.json`, or copy an exact configuration from the [MCP guide](mcp.md).
+
+```text
+$ git-a2a mcp
+```
+
+## version
+
+`git-a2a version [--check]` prints version, commit, target, and install channel. `--check` alone
+uses the network and exits `1` when an update is available. If only prereleases exist, it reports
+that no stable release is published and exits `0`; prereleases never become `latest`.
+
+```text
+$ git-a2a version
+git-a2a 1.0.0 (2a46f1368876, darwin/arm64, channel=binary)
+```
+
+## upgrade
+
+`git-a2a upgrade [--to VERSION]` downloads, checksum-verifies, and atomically replaces only a
+standalone binary-channel installation. Managed channels exit `1` with their native update
+command.
+
+```text
+$ git-a2a upgrade --to 1.0.1
+upgraded git-a2a 1.0.0 -> 1.0.1
+```