git-a2a 1.0.1 → 1.1.0-rc.2

package/skills/git-a2a/references/manifest-reference.md

@@ -0,0 +1,944 @@
+<!-- Code generated by tools/gen-reference.py; DO NOT EDIT. -->
+# Manifest field reference
+
+This reference is generated from the compiled normative `spec/_.hint` and
+`spec/schema/a2amodule.schema.json`. Run `make docs-check` to detect drift.
+Paths use `[]` for one array entry. Unknown `x-*` extension keys are allowed at every
+declared object boundary and are preserved; other unknown keys are validation errors.
+
+## `schema`
+
+- Type: integer; required.
+- Default: exactly `1`.
+- Allowed values: exact value `1`.
+- Normative source: [`spec/_.hint:100`](../spec/_.hint#L100).
+- Example: see the [public library manifest](https://github.com/neprel/git-a2a-demo-acme-lib/blob/main/a2amodule.yml) and [consumer manifest](https://github.com/neprel/git-a2a-demo-acme-app/blob/main/a2amodule.yml).
+
+Behavior and consequence:
+
+integer; the format version of this file. Value `1` for this specification. A consumer that
+sees a larger value than it knows must refuse the file (exit 2), not guess.
+
+## `module`
+
+- Type: object; required.
+- Default: none declared.
+- Allowed values: schema type plus the normative behavior in this entry.
+- Normative source: [`spec/_.hint:105`](../spec/_.hint#L105).
+- Example: see the [public library manifest](https://github.com/neprel/git-a2a-demo-acme-lib/blob/main/a2amodule.yml) and [consumer manifest](https://github.com/neprel/git-a2a-demo-acme-app/blob/main/a2amodule.yml).
+
+Behavior and consequence:
+
+object; the module description. See [#module](../spec/_.hint).
+
+## `agents`
+
+- Type: array of object; optional.
+- Default: none declared.
+- Allowed values: schema type plus the normative behavior in this entry.
+- Normative source: [`spec/_.hint:109`](../spec/_.hint#L109).
+- Example: see the [public library manifest](https://github.com/neprel/git-a2a-demo-acme-lib/blob/main/a2amodule.yml) and [consumer manifest](https://github.com/neprel/git-a2a-demo-acme-app/blob/main/a2amodule.yml).
+
+Behavior and consequence:
+
+list of agent bindings, see [#agent](../spec/_.hint). Empty or absent means "no agent owns this; treat
+as a plain library" — still importable, nobody to ask.
+
+## `policy`
+
+- Type: object; optional.
+- Default: none declared.
+- Allowed values: schema type plus the normative behavior in this entry.
+- Normative source: [`spec/_.hint:114`](../spec/_.hint#L114).
+- Example: see the [public library manifest](https://github.com/neprel/git-a2a-demo-acme-lib/blob/main/a2amodule.yml) and [consumer manifest](https://github.com/neprel/git-a2a-demo-acme-app/blob/main/a2amodule.yml).
+
+Behavior and consequence:
+
+object, see [#policy](../spec/_.hint). Routing defaults and consumer permissions.
+
+## `dependencies`
+
+- Type: array of object; optional.
+- Default: none declared.
+- Allowed values: schema type plus the normative behavior in this entry.
+- Normative source: [`spec/_.hint:118`](../spec/_.hint#L118).
+- Example: see the [public library manifest](https://github.com/neprel/git-a2a-demo-acme-lib/blob/main/a2amodule.yml) and [consumer manifest](https://github.com/neprel/git-a2a-demo-acme-app/blob/main/a2amodule.yml).
+
+Behavior and consequence:
+
+list, see [#dependency](../spec/_.hint). Modules this module depends on.
+
+## `module.id`
+
+- Type: string; required.
+- Default: none declared.
+- Allowed values: pattern `^[a-z0-9][a-z0-9._-]{0,63}$`.
+- Normative source: [`spec/_.hint:124`](../spec/_.hint#L124).
+- Example: see the [public library manifest](https://github.com/neprel/git-a2a-demo-acme-lib/blob/main/a2amodule.yml) and [consumer manifest](https://github.com/neprel/git-a2a-demo-acme-app/blob/main/a2amodule.yml).
+
+Behavior and consequence:
+
+string, required. Stable identifier, `^[a-z0-9][a-z0-9._-]{0,63}$`. Consumers refer to the
+dependency by this id and the lock keys on it; `add` verifies that the fetched manifest's `id`
+equals the id the consumer expected (when given) and otherwise adopts it. Renaming an id is a
+breaking change for every consumer.
+
+## `module.name`
+
+- Type: string; optional.
+- Default: `module.id`.
+- Allowed values: schema type plus the normative behavior in this entry.
+- Normative source: [`spec/_.hint:131`](../spec/_.hint#L131).
+- Example: see the [public library manifest](https://github.com/neprel/git-a2a-demo-acme-lib/blob/main/a2amodule.yml) and [consumer manifest](https://github.com/neprel/git-a2a-demo-acme-app/blob/main/a2amodule.yml).
+
+Behavior and consequence:
+
+string. Display name. Defaults to `id`.
+
+## `module.description`
+
+- Type: string; optional.
+- Default: none declared.
+- Allowed values: schema type plus the normative behavior in this entry.
+- Normative source: [`spec/_.hint:135`](../spec/_.hint#L135).
+- Example: see the [public library manifest](https://github.com/neprel/git-a2a-demo-acme-lib/blob/main/a2amodule.yml) and [consumer manifest](https://github.com/neprel/git-a2a-demo-acme-app/blob/main/a2amodule.yml).
+
+Behavior and consequence:
+
+string, recommended. One paragraph answering "what is this and what is it for" — it is what a
+consumer's agent reads in its roster, so it should also say what kind of questions the owner
+expects. Whitespace is normalised when rendered.
+
+## `module.languages`
+
+- Type: array of string; optional.
+- Default: none declared.
+- Allowed values: open vocabulary; see the known-values table in this entry.
+- Normative source: [`spec/_.hint:141`](../spec/_.hint#L141).
+- Example: see the [public library manifest](https://github.com/neprel/git-a2a-demo-acme-lib/blob/main/a2amodule.yml) and [consumer manifest](https://github.com/neprel/git-a2a-demo-acme-app/blob/main/a2amodule.yml).
+
+Behavior and consequence:
+
+list of strings, open vocabulary and informative. Known tokens and their behavior are in
+`vocabulary_languages`. Not used for wiring; `exports` is. Changing it changes discovery metadata
+only; unknown values are accepted and preserved.
+
+Known values:
+
+| Known value | What the tool does | Consequence of changing it | Unknown value |
+| --- | --- | --- | --- |
+| `typescript` | Reports TypeScript as module metadata. | Changes discovery/documentation only; wiring still follows exports. | Accepted and preserved as informative metadata. |
+| `python` | Reports Python as module metadata. | Changes discovery/documentation only; wiring still follows exports. | Accepted and preserved as informative metadata. |
+| `go` | Reports Go as module metadata. | Changes discovery/documentation only; wiring still follows exports. | Accepted and preserved as informative metadata. |
+| `rust`, `swift`, `dart`, `ruby`, `php`, `elixir`, `haskell`, `zig`, `clojure`, `nix` | Reports the declared language as module metadata. | Changes discovery/documentation only; wiring still follows exports. | Accepted and preserved as informative metadata. |
+
+## `module.surface`
+
+- Type: string; optional.
+- Default: none declared.
+- Allowed values: minimum length 1.
+- Normative source: [`spec/_.hint:147`](../spec/_.hint#L147).
+- Example: see the [public library manifest](https://github.com/neprel/git-a2a-demo-acme-lib/blob/main/a2amodule.yml) and [consumer manifest](https://github.com/neprel/git-a2a-demo-acme-app/blob/main/a2amodule.yml).
+
+Behavior and consequence:
+
+string; relative directory path. Published content for consumers. Absent means nothing is
+published beyond the manifest.
+
+## `module.repository`
+
+- Type: string; optional.
+- Default: none declared.
+- Allowed values: schema type plus the normative behavior in this entry.
+- Normative source: [`spec/_.hint:152`](../spec/_.hint#L152).
+- Example: see the [public library manifest](https://github.com/neprel/git-a2a-demo-acme-lib/blob/main/a2amodule.yml) and [consumer manifest](https://github.com/neprel/git-a2a-demo-acme-app/blob/main/a2amodule.yml).
+
+Behavior and consequence:
+
+string; the canonical git URL of this module as its owner declares it. Lets a consumer that
+obtained the module from elsewhere (a fork, a mirror, a copy) see that it is not on the
+canonical source — and that the `agents` listed may belong to the original owner rather than
+to whoever maintains the copy. Informative; never used to fetch.
+
+## `module.moved-to`
+
+- Type: object; optional.
+- Default: none declared.
+- Allowed values: schema type plus the normative behavior in this entry.
+- Normative source: [`spec/_.hint:159`](../spec/_.hint#L159).
+- Example: see the [public library manifest](https://github.com/neprel/git-a2a-demo-acme-lib/blob/main/a2amodule.yml) and [consumer manifest](https://github.com/neprel/git-a2a-demo-acme-app/blob/main/a2amodule.yml).
+
+Behavior and consequence:
+
+object, optional: `git` (string, required; the new canonical URL), `path` (string), `notes`
+(string). An owner leaves it in the last manifest at the old location when the module moves.
+Consumers are told on `update` and follow it only on explicit request; a tool never switches a
+source silently.
+
+## `module.docs`
+
+- Type: string; optional.
+- Default: none declared.
+- Allowed values: schema type plus the normative behavior in this entry.
+- Normative source: [`spec/_.hint:166`](../spec/_.hint#L166).
+- Example: see the [public library manifest](https://github.com/neprel/git-a2a-demo-acme-lib/blob/main/a2amodule.yml) and [consumer manifest](https://github.com/neprel/git-a2a-demo-acme-app/blob/main/a2amodule.yml).
+
+Behavior and consequence:
+
+string; URL of human documentation.
+
+## `module.release`
+
+- Type: object; optional.
+- Default: none declared.
+- Allowed values: schema type plus the normative behavior in this entry.
+- Normative source: [`spec/_.hint:170`](../spec/_.hint#L170).
+- Example: see the [public library manifest](https://github.com/neprel/git-a2a-demo-acme-lib/blob/main/a2amodule.yml) and [consumer manifest](https://github.com/neprel/git-a2a-demo-acme-app/blob/main/a2amodule.yml).
+
+Behavior and consequence:
+
+object: `channel` (string, the ref consumers should follow by default, e.g. `main`), `tags`
+(boolean, whether semver tags are published), `notes` (string, free text, e.g. "main is the only
+release channel"). `release.channel` is the default `ref` a consumer gets when it adds this
+module without naming one.
+
+## `module.exports`
+
+- Type: array of object; optional.
+- Default: none declared.
+- Allowed values: schema type plus the normative behavior in this entry.
+- Normative source: [`spec/_.hint:177`](../spec/_.hint#L177).
+- Example: see the [public library manifest](https://github.com/neprel/git-a2a-demo-acme-lib/blob/main/a2amodule.yml) and [consumer manifest](https://github.com/neprel/git-a2a-demo-acme-app/blob/main/a2amodule.yml).
+
+Behavior and consequence:
+
+list of export entries; how to import this module per ecosystem. Each entry: `ecosystem`
+(string, required; use package-url type names: `npm`, `pypi`, `golang`, `cargo`, `maven`,
+`nuget`, `swift`, `cocoapods`, `pub`, `gem`, `composer`, `hex`, `hackage`, …), `name` (string,
+required; the name the ecosystem imports: npm package name, PEP 503 distribution name, Go module
+path, crate name, Maven `group:artifact`), `path` (string, optional; subdirectory containing the
+ecosystem's own manifest, default the module directory), `notes` (string, optional; anything a
+wiring tool or agent must know, e.g. "vanity import path, needs replace", "prepare script builds
+dist"). Ecosystem-specific keys are allowed under `x-<ecosystem>-*`.
+
+## `module.moved-to.git`
+
+- Type: string; required.
+- Default: none declared.
+- Allowed values: schema type plus the normative behavior in this entry.
+- Normative source: [`spec/_.hint:193`](../spec/_.hint#L193).
+- Example: see the [public library manifest](https://github.com/neprel/git-a2a-demo-acme-lib/blob/main/a2amodule.yml) and [consumer manifest](https://github.com/neprel/git-a2a-demo-acme-app/blob/main/a2amodule.yml).
+
+Behavior and consequence:
+
+string, required. New canonical Git URL. Changing it changes the destination offered to users;
+consumers remain on the current source until an explicit `set --git`.
+
+## `module.moved-to.path`
+
+- Type: string; optional.
+- Default: `.`.
+- Allowed values: minimum length 1.
+- Normative source: [`spec/_.hint:198`](../spec/_.hint#L198).
+- Example: see the [public library manifest](https://github.com/neprel/git-a2a-demo-acme-lib/blob/main/a2amodule.yml) and [consumer manifest](https://github.com/neprel/git-a2a-demo-acme-app/blob/main/a2amodule.yml).
+
+Behavior and consequence:
+
+string, optional relative path, default `.`. Subdirectory containing the moved module. Changing
+it changes the destination module root offered with the new Git URL.
+
+## `module.moved-to.notes`
+
+- Type: string; optional.
+- Default: none declared.
+- Allowed values: schema type plus the normative behavior in this entry.
+- Normative source: [`spec/_.hint:203`](../spec/_.hint#L203).
+- Example: see the [public library manifest](https://github.com/neprel/git-a2a-demo-acme-lib/blob/main/a2amodule.yml) and [consumer manifest](https://github.com/neprel/git-a2a-demo-acme-app/blob/main/a2amodule.yml).
+
+Behavior and consequence:
+
+string, optional. Human migration context printed with the move notice. Changing it changes only
+the guidance, never the source automatically.
+
+## `module.release.channel`
+
+- Type: string; optional.
+- Default: none declared.
+- Allowed values: schema type plus the normative behavior in this entry.
+- Normative source: [`spec/_.hint:212`](../spec/_.hint#L212).
+- Example: see the [public library manifest](https://github.com/neprel/git-a2a-demo-acme-lib/blob/main/a2amodule.yml) and [consumer manifest](https://github.com/neprel/git-a2a-demo-acme-app/blob/main/a2amodule.yml).
+
+Behavior and consequence:
+
+string, optional. Default ref used by `add` when the consumer supplies no ref, commonly `main`.
+Changing it affects future adds; existing consumers retain their declared ref until `set`.
+
+## `module.release.tags`
+
+- Type: boolean; optional.
+- Default: `false`.
+- Allowed values: schema type plus the normative behavior in this entry.
+- Normative source: [`spec/_.hint:217`](../spec/_.hint#L217).
+- Example: see the [public library manifest](https://github.com/neprel/git-a2a-demo-acme-lib/blob/main/a2amodule.yml) and [consumer manifest](https://github.com/neprel/git-a2a-demo-acme-app/blob/main/a2amodule.yml).
+
+Behavior and consequence:
+
+boolean, optional, default `false`. Declares whether the owner publishes semantic-version tags.
+Changing it changes what consumers may reasonably select with `set --ref`; it does not create tags.
+
+## `module.release.notes`
+
+- Type: string; optional.
+- Default: none declared.
+- Allowed values: schema type plus the normative behavior in this entry.
+- Normative source: [`spec/_.hint:222`](../spec/_.hint#L222).
+- Example: see the [public library manifest](https://github.com/neprel/git-a2a-demo-acme-lib/blob/main/a2amodule.yml) and [consumer manifest](https://github.com/neprel/git-a2a-demo-acme-app/blob/main/a2amodule.yml).
+
+Behavior and consequence:
+
+string, optional. Free release-channel guidance shown to consumers. Changing it changes guidance
+only and does not resolve or move a dependency.
+
+## `module.exports[].ecosystem`
+
+- Type: string; required.
+- Default: none declared.
+- Allowed values: minimum length 1; open vocabulary; see the known-values table in this entry.
+- Normative source: [`spec/_.hint:231`](../spec/_.hint#L231).
+- Example: see the [public library manifest](https://github.com/neprel/git-a2a-demo-acme-lib/blob/main/a2amodule.yml) and [consumer manifest](https://github.com/neprel/git-a2a-demo-acme-app/blob/main/a2amodule.yml).
+
+Behavior and consequence:
+
+string, required, open vocabulary. Known values and adapter behavior are in
+`vocabulary_ecosystems`. Changing it selects a different adapter and therefore a different native
+manifest; an unknown value remains valid published metadata but has no wiring adapter.
+
+Known values:
+
+| Known value | What the tool does | Consequence of changing it | Unknown value |
+| --- | --- | --- | --- |
+| `npm` | Wires a Git dependency in package.json through npm/yarn/pnpm/bun. | Selects the JavaScript package name and adapter. | Accepted; without an adapter it remains published metadata and cannot be wired. |
+| `pypi` | Wires a Git dependency in pyproject.toml through uv. | Selects the Python distribution name and adapter. | Accepted; without an adapter it remains published metadata and cannot be wired. |
+| `golang` | Wires the Go module at the locked commit with go.mod edits. | Selects the Go import path and adapter. | Accepted; without an adapter it remains published metadata and cannot be wired. |
+| `cargo`, `swift`, `pub`, `gem`, `composer`, `hex`, `hackage`, `zig`, `clojure`, `nix` | Uses the matching native Git-dependency adapter. | Selects a different native manifest and package identity. | Accepted; without an adapter it remains published metadata and cannot be wired. |
+
+## `module.exports[].name`
+
+- Type: string; required.
+- Default: none declared.
+- Allowed values: minimum length 1.
+- Normative source: [`spec/_.hint:237`](../spec/_.hint#L237).
+- Example: see the [public library manifest](https://github.com/neprel/git-a2a-demo-acme-lib/blob/main/a2amodule.yml) and [consumer manifest](https://github.com/neprel/git-a2a-demo-acme-app/blob/main/a2amodule.yml).
+
+Behavior and consequence:
+
+string, required. Native package/import name in the named ecosystem. Changing it rewires the
+consumer from the old native entry to the new one on the next mutation or `wire`.
+
+## `module.exports[].path`
+
+- Type: string; optional.
+- Default: the module directory (`.`).
+- Allowed values: minimum length 1.
+- Normative source: [`spec/_.hint:242`](../spec/_.hint#L242).
+- Example: see the [public library manifest](https://github.com/neprel/git-a2a-demo-acme-lib/blob/main/a2amodule.yml) and [consumer manifest](https://github.com/neprel/git-a2a-demo-acme-app/blob/main/a2amodule.yml).
+
+Behavior and consequence:
+
+string, optional relative path, default `.`. Subdirectory containing the ecosystem package.
+Changing it changes the Git subdirectory expression; unsupported adapters report `not wired`.
+
+## `module.exports[].notes`
+
+- Type: string; optional.
+- Default: none declared.
+- Allowed values: schema type plus the normative behavior in this entry.
+- Normative source: [`spec/_.hint:247`](../spec/_.hint#L247).
+- Example: see the [public library manifest](https://github.com/neprel/git-a2a-demo-acme-lib/blob/main/a2amodule.yml) and [consumer manifest](https://github.com/neprel/git-a2a-demo-acme-app/blob/main/a2amodule.yml).
+
+Behavior and consequence:
+
+string, optional. Export-specific facts shown to tools and agents. Changing it changes published
+guidance but does not itself alter adapter behavior.
+
+## `agents[].name`
+
+- Type: string; required.
+- Default: none declared.
+- Allowed values: minimum length 1.
+- Normative source: [`spec/_.hint:256`](../spec/_.hint#L256).
+- Example: see the [public library manifest](https://github.com/neprel/git-a2a-demo-acme-lib/blob/main/a2amodule.yml) and [consumer manifest](https://github.com/neprel/git-a2a-demo-acme-app/blob/main/a2amodule.yml).
+
+Behavior and consequence:
+
+string, required. The agent's own name — must equal `name` in its A2A card when a card is given.
+An agent may appear in many modules (one agent, many repositories) and a module may list many
+agents (one repository, many agents), so `name` must be stable across repositories. Identity
+for de-duplication across modules is the `card` URL when present, else `name`; two bindings in
+different modules with the same card URL are the same agent, and tools may merge what they know
+about it. Names are scoped to whoever controls the card URL, so a public ecosystem never relies
+on a bare name being globally unique.
+
+## `agents[].role`
+
+- Type: string; required.
+- Default: none declared.
+- Allowed values: minimum length 1; open vocabulary; see the known-values table in this entry.
+- Normative source: [`spec/_.hint:266`](../spec/_.hint#L266).
+- Example: see the [public library manifest](https://github.com/neprel/git-a2a-demo-acme-lib/blob/main/a2amodule.yml) and [consumer manifest](https://github.com/neprel/git-a2a-demo-acme-app/blob/main/a2amodule.yml).
+
+Behavior and consequence:
+
+string, required, open vocabulary. A role says what the agent owns for this module; core values
+and routing consequences are in `vocabulary_roles`. Unknown roles are accepted and participate in
+routing when `policy.intents` names the same token.
+
+Known values:
+
+| Known value | What the tool does | Consequence of changing it | Unknown value |
+| --- | --- | --- | --- |
+| `owner` | Default routing target; identifies the agent that commits, merges, and releases. | Requests using the default route select a different binding. | Accepted and routed when policy names the same token. |
+| `maintainer` | Routes intents mapped to a maintainer. | Changes which bindings match those intents. | Accepted and routed when policy names the same token. |
+| `spec` | Routes specification, task, or sequencing ownership. | Changes which bindings match policy entries such as `change: spec`. | Accepted and routed when policy names the same token. |
+| `reviewer` | Routes review ownership. | Changes which bindings match review policy. | Accepted and routed when policy names the same token. |
+| `support` | Routes support ownership. | Changes which bindings match support policy. | Accepted and routed when policy names the same token. |
+
+## `agents[].scope`
+
+- Type: array of string; optional.
+- Default: `["**"]`.
+- Allowed values: schema type plus the normative behavior in this entry.
+- Normative source: [`spec/_.hint:272`](../spec/_.hint#L272).
+- Example: see the [public library manifest](https://github.com/neprel/git-a2a-demo-acme-lib/blob/main/a2amodule.yml) and [consumer manifest](https://github.com/neprel/git-a2a-demo-acme-app/blob/main/a2amodule.yml).
+
+Behavior and consequence:
+
+list of glob patterns relative to the module directory. What this agent answers for and may
+change. Default `["**"]`. Two agents may overlap; resolution prefers the more specific match,
+then declared order.
+
+## `agents[].card`
+
+- Type: string; optional.
+- Default: none declared.
+- Allowed values: minimum length 1.
+- Normative source: [`spec/_.hint:278`](../spec/_.hint#L278).
+- Example: see the [public library manifest](https://github.com/neprel/git-a2a-demo-acme-lib/blob/main/a2amodule.yml) and [consumer manifest](https://github.com/neprel/git-a2a-demo-acme-app/blob/main/a2amodule.yml).
+
+Behavior and consequence:
+
+string. URL of the agent's A2A Agent Card (`https://…/.well-known/agent-card.json`) or a
+repository-relative path to a card file (A2A "direct configuration"). When present the card is
+the authority for `description`, `skills`, interfaces and security; git-a2a snapshots it.
+
+## `agents[].description`
+
+- Type: string; optional.
+- Default: none declared.
+- Allowed values: schema type plus the normative behavior in this entry.
+- Normative source: [`spec/_.hint:284`](../spec/_.hint#L284).
+- Example: see the [public library manifest](https://github.com/neprel/git-a2a-demo-acme-lib/blob/main/a2amodule.yml) and [consumer manifest](https://github.com/neprel/git-a2a-demo-acme-app/blob/main/a2amodule.yml).
+
+Behavior and consequence:
+
+string. Only when no card is available or to add module-specific wording ("for this repository,
+ask it about …"). Never a copy of the card's description.
+
+## `agents[].contacts`
+
+- Type: array of object; optional.
+- Default: none declared.
+- Allowed values: open vocabulary; see the known-values table in this entry.
+- Normative source: [`spec/_.hint:289`](../spec/_.hint#L289).
+- Example: see the [public library manifest](https://github.com/neprel/git-a2a-demo-acme-lib/blob/main/a2amodule.yml) and [consumer manifest](https://github.com/neprel/git-a2a-demo-acme-app/blob/main/a2amodule.yml).
+
+Behavior and consequence:
+
+ordered list. Each contact: `intents` (list of strings, required; `"*"` allowed), `kind`
+(string, required; open vocabulary, see [#contact\_kinds](../spec/_.hint)), `note` (string,
+optional; free-text instructions shown verbatim to the asker, e.g. "state the version you are
+on"), plus kind-specific keys. Order expresses preference within an intent.
+
+## `agents[].trust`
+
+- Type: object; optional.
+- Default: none declared.
+- Allowed values: schema type plus the normative behavior in this entry.
+- Normative source: [`spec/_.hint:296`](../spec/_.hint#L296).
+- Example: see the [public library manifest](https://github.com/neprel/git-a2a-demo-acme-lib/blob/main/a2amodule.yml) and [consumer manifest](https://github.com/neprel/git-a2a-demo-acme-app/blob/main/a2amodule.yml).
+
+Behavior and consequence:
+
+object, optional: `signatures` (boolean, whether the card is JWS-signed and must verify),
+`accepts-external` (boolean, whether requests from agents outside the owner's organisation are
+welcome), `x-*`. Defaults: no verification required, external not stated.
+
+When `signatures: true`, at least one A2A Agent Card detached JWS signature must verify over the
+RFC 8785 canonical card with the top-level `signatures` member excluded. The protected header
+identifies the algorithm, key id, and JWKS URL. An unsigned card, an invalid signature, or an
+unavailable key with no local cache makes `status` fail; `update` retains the dependency update
+but prints a trust warning. JWKS responses are timeout-bounded and cached only in `.git-a2a/`.
+
+## `agents[].contacts[].intents`
+
+- Type: array of string; required.
+- Default: none declared.
+- Allowed values: minimum 1 item(s); open vocabulary; see the known-values table in this entry.
+- Normative source: [`spec/_.hint:313`](../spec/_.hint#L313).
+- Example: see the [public library manifest](https://github.com/neprel/git-a2a-demo-acme-lib/blob/main/a2amodule.yml) and [consumer manifest](https://github.com/neprel/git-a2a-demo-acme-app/blob/main/a2amodule.yml).
+
+Behavior and consequence:
+
+list of strings, required and non-empty, open vocabulary; `"*"` is the fallback. Changing the
+list changes which requests may select this contact. Core values, fallback behavior, and unknown
+handling are in `vocabulary_intents`.
+
+Known values:
+
+| Known value | What the tool does | Consequence of changing it | Unknown value |
+| --- | --- | --- | --- |
+| `question` | Routes a request for explanation; defaults to role `owner`. | Selects contacts declaring `question` or `*`. | Accepted; policy and contacts can route any matching token. |
+| `change` | Routes a proposed behavior/API change. | Selects contacts declaring `change` or `*`. | Accepted; policy and contacts can route any matching token. |
+| `bug` | Routes a defect report. | Selects contacts declaring `bug` or `*`. | Accepted; policy and contacts can route any matching token. |
+| `review` | Routes a review request. | Selects contacts declaring `review` or `*`. | Accepted; policy and contacts can route any matching token. |
+| `incident` | Routes an operational incident. | Selects contacts declaring `incident` or `*`. | Accepted; policy and contacts can route any matching token. |
+| `*` | Acts as a contact fallback after exact intent matches. | Broadens that contact to unmatched intents. | Accepted; any other unknown token is an exact-match intent. |
+
+## `agents[].contacts[].kind`
+
+- Type: string; required.
+- Default: none declared.
+- Allowed values: minimum length 1; open vocabulary; see the known-values table in this entry.
+- Normative source: [`spec/_.hint:319`](../spec/_.hint#L319).
+- Example: see the [public library manifest](https://github.com/neprel/git-a2a-demo-acme-lib/blob/main/a2amodule.yml) and [consumer manifest](https://github.com/neprel/git-a2a-demo-acme-app/blob/main/a2amodule.yml).
+
+Behavior and consequence:
+
+string, required, open vocabulary. Changing it selects another delivery driver or instruction
+renderer and changes which kind-specific fields are valid. Known values and unknown handling are
+in `contact_kinds`.
+
+Known values:
+
+The kind vocabulary is open; these kinds have defined keys and delivery behavior:
+
+| Kind | Allowed kind-specific keys | Driver or instruction | Consequence of changing it | Unknown kind |
+| --- | --- | --- | --- | --- |
+| `a2a` | `url`, optional `skill` | Sends A2A `SendMessage` JSON-RPC 1.0; the only kind derivable from a card. | Changes the JSON-RPC endpoint or target skill. | Accepted, but no delivery driver is selected. |
+| `github-issue` | `repo`, optional `labels`, `template` | Creates an issue through `gh`, then GitHub REST fallback. | Changes the repository, labels, or issue template. | Accepted, but no delivery driver is selected. |
+| `gitlab-issue` | `repo`, optional `labels`, `template` | Prints an instruction; no reference delivery driver. | Changes the instructed issue destination. | Accepted, but no delivery driver is selected. |
+| `email` | `address`, optional `subject-prefix` | Prints an email instruction; does not send mail. | Changes the instructed recipient or subject. | Accepted, but no delivery driver is selected. |
+| `jira` | `url`, `project`, optional `issue-type` | Prints a Jira instruction. | Changes the instructed site, project, or issue type. | Accepted, but no delivery driver is selected. |
+| `mattermost`, `slack`, `discord`, `telegram`, `teams` | `channel`, `handle`, optional `server` | Prints a chat instruction. | Changes the instructed workspace, channel, or handle. | Accepted, but no delivery driver is selected. |
+| `url` | `url`, optional `note` | Prints the URL instruction. | Changes the instructed destination. | Accepted, but no delivery driver is selected. |
+
+An unknown kind is rendered as `kind: <value>` with its extension keys, is never a validation
+error, and cannot be delivered by `contact` until a driver exists.
+
+## `agents[].contacts[].note`
+
+- Type: string; optional.
+- Default: none declared.
+- Allowed values: schema type plus the normative behavior in this entry.
+- Normative source: [`spec/_.hint:325`](../spec/_.hint#L325).
+- Example: see the [public library manifest](https://github.com/neprel/git-a2a-demo-acme-lib/blob/main/a2amodule.yml) and [consumer manifest](https://github.com/neprel/git-a2a-demo-acme-app/blob/main/a2amodule.yml).
+
+Behavior and consequence:
+
+string, optional. Instructions printed verbatim after the route. Changing it changes the asker's
+guidance, not routing priority or delivery mechanics.
+
+## `agents[].contacts[].url`
+
+- Type: string; optional.
+- Default: none declared.
+- Allowed values: schema type plus the normative behavior in this entry.
+- Normative source: [`spec/_.hint:330`](../spec/_.hint#L330).
+- Example: see the [public library manifest](https://github.com/neprel/git-a2a-demo-acme-lib/blob/main/a2amodule.yml) and [consumer manifest](https://github.com/neprel/git-a2a-demo-acme-app/blob/main/a2amodule.yml).
+
+Behavior and consequence:
+
+string, optional for `a2a`, `jira`, and `url`. Changing it changes the service or instruction
+destination; for A2A it is the JSON-RPC endpoint.
+
+## `agents[].contacts[].skill`
+
+- Type: string; optional.
+- Default: none declared.
+- Allowed values: schema type plus the normative behavior in this entry.
+- Normative source: [`spec/_.hint:335`](../spec/_.hint#L335).
+- Example: see the [public library manifest](https://github.com/neprel/git-a2a-demo-acme-lib/blob/main/a2amodule.yml) and [consumer manifest](https://github.com/neprel/git-a2a-demo-acme-app/blob/main/a2amodule.yml).
+
+Behavior and consequence:
+
+string, optional for `a2a`. Skill identifier requested from the remote agent. Changing it changes
+the A2A target skill without changing the endpoint.
+
+## `agents[].contacts[].address`
+
+- Type: string; optional.
+- Default: none declared.
+- Allowed values: schema type plus the normative behavior in this entry.
+- Normative source: [`spec/_.hint:340`](../spec/_.hint#L340).
+- Example: see the [public library manifest](https://github.com/neprel/git-a2a-demo-acme-lib/blob/main/a2amodule.yml) and [consumer manifest](https://github.com/neprel/git-a2a-demo-acme-app/blob/main/a2amodule.yml).
+
+Behavior and consequence:
+
+string, optional for `email`. Destination email address. Changing it changes the printed email
+instruction; the reference CLI does not send email.
+
+## `agents[].contacts[].subject-prefix`
+
+- Type: string; optional.
+- Default: none declared.
+- Allowed values: schema type plus the normative behavior in this entry.
+- Normative source: [`spec/_.hint:345`](../spec/_.hint#L345).
+- Example: see the [public library manifest](https://github.com/neprel/git-a2a-demo-acme-lib/blob/main/a2amodule.yml) and [consumer manifest](https://github.com/neprel/git-a2a-demo-acme-app/blob/main/a2amodule.yml).
+
+Behavior and consequence:
+
+string, optional for `email`. Prefix suggested for the email subject. Changing it changes only
+the printed instruction.
+
+## `agents[].contacts[].repo`
+
+- Type: string; optional.
+- Default: none declared.
+- Allowed values: schema type plus the normative behavior in this entry.
+- Normative source: [`spec/_.hint:350`](../spec/_.hint#L350).
+- Example: see the [public library manifest](https://github.com/neprel/git-a2a-demo-acme-lib/blob/main/a2amodule.yml) and [consumer manifest](https://github.com/neprel/git-a2a-demo-acme-app/blob/main/a2amodule.yml).
+
+Behavior and consequence:
+
+string, optional for `github-issue` and `gitlab-issue`, in `owner/name` form. Changing it changes
+the repository where the issue driver delivers the request.
+
+## `agents[].contacts[].labels`
+
+- Type: array of string; optional.
+- Default: none declared.
+- Allowed values: schema type plus the normative behavior in this entry.
+- Normative source: [`spec/_.hint:355`](../spec/_.hint#L355).
+- Example: see the [public library manifest](https://github.com/neprel/git-a2a-demo-acme-lib/blob/main/a2amodule.yml) and [consumer manifest](https://github.com/neprel/git-a2a-demo-acme-app/blob/main/a2amodule.yml).
+
+Behavior and consequence:
+
+list of strings, optional for issue kinds. Changing it changes labels requested when an issue is
+created; a missing label is a delivery error from the host.
+
+## `agents[].contacts[].template`
+
+- Type: string; optional.
+- Default: none declared.
+- Allowed values: schema type plus the normative behavior in this entry.
+- Normative source: [`spec/_.hint:360`](../spec/_.hint#L360).
+- Example: see the [public library manifest](https://github.com/neprel/git-a2a-demo-acme-lib/blob/main/a2amodule.yml) and [consumer manifest](https://github.com/neprel/git-a2a-demo-acme-app/blob/main/a2amodule.yml).
+
+Behavior and consequence:
+
+string, optional for issue kinds. Issue form/template name. Changing it changes the requested
+host template without changing routing.
+
+## `agents[].contacts[].project`
+
+- Type: string; optional.
+- Default: none declared.
+- Allowed values: schema type plus the normative behavior in this entry.
+- Normative source: [`spec/_.hint:365`](../spec/_.hint#L365).
+- Example: see the [public library manifest](https://github.com/neprel/git-a2a-demo-acme-lib/blob/main/a2amodule.yml) and [consumer manifest](https://github.com/neprel/git-a2a-demo-acme-app/blob/main/a2amodule.yml).
+
+Behavior and consequence:
+
+string, optional for `jira`. Project key. Changing it changes the Jira project named in the
+instruction.
+
+## `agents[].contacts[].issue-type`
+
+- Type: string; optional.
+- Default: none declared.
+- Allowed values: schema type plus the normative behavior in this entry.
+- Normative source: [`spec/_.hint:370`](../spec/_.hint#L370).
+- Example: see the [public library manifest](https://github.com/neprel/git-a2a-demo-acme-lib/blob/main/a2amodule.yml) and [consumer manifest](https://github.com/neprel/git-a2a-demo-acme-app/blob/main/a2amodule.yml).
+
+Behavior and consequence:
+
+string, optional for `jira`. Issue type. Changing it changes the Jira issue kind named in the
+instruction.
+
+## `agents[].contacts[].channel`
+
+- Type: string; optional.
+- Default: none declared.
+- Allowed values: schema type plus the normative behavior in this entry.
+- Normative source: [`spec/_.hint:375`](../spec/_.hint#L375).
+- Example: see the [public library manifest](https://github.com/neprel/git-a2a-demo-acme-lib/blob/main/a2amodule.yml) and [consumer manifest](https://github.com/neprel/git-a2a-demo-acme-app/blob/main/a2amodule.yml).
+
+Behavior and consequence:
+
+string, optional for chat kinds. Channel name or id. Changing it changes the printed chat
+destination; chat contacts are instruction-only.
+
+## `agents[].contacts[].handle`
+
+- Type: string; optional.
+- Default: none declared.
+- Allowed values: schema type plus the normative behavior in this entry.
+- Normative source: [`spec/_.hint:380`](../spec/_.hint#L380).
+- Example: see the [public library manifest](https://github.com/neprel/git-a2a-demo-acme-lib/blob/main/a2amodule.yml) and [consumer manifest](https://github.com/neprel/git-a2a-demo-acme-app/blob/main/a2amodule.yml).
+
+Behavior and consequence:
+
+string, optional for chat kinds. Agent mention or handle. Changing it changes whom the asker is
+told to address.
+
+## `agents[].contacts[].server`
+
+- Type: string; optional.
+- Default: none declared.
+- Allowed values: schema type plus the normative behavior in this entry.
+- Normative source: [`spec/_.hint:385`](../spec/_.hint#L385).
+- Example: see the [public library manifest](https://github.com/neprel/git-a2a-demo-acme-lib/blob/main/a2amodule.yml) and [consumer manifest](https://github.com/neprel/git-a2a-demo-acme-app/blob/main/a2amodule.yml).
+
+Behavior and consequence:
+
+string, optional for chat kinds. Workspace or server URL/name. Changing it disambiguates the
+printed chat destination.
+
+## `agents[].trust.signatures`
+
+- Type: boolean; optional.
+- Default: `false`.
+- Allowed values: schema type plus the normative behavior in this entry.
+- Normative source: [`spec/_.hint:394`](../spec/_.hint#L394).
+- Example: see the [public library manifest](https://github.com/neprel/git-a2a-demo-acme-lib/blob/main/a2amodule.yml) and [consumer manifest](https://github.com/neprel/git-a2a-demo-acme-app/blob/main/a2amodule.yml).
+
+Behavior and consequence:
+
+boolean, optional, default `false`. When changed to `true`, unsigned, invalid, or unverifiable
+cards make `status` fail and make `update` warn while retaining the dependency update.
+
+## `agents[].trust.accepts-external`
+
+- Type: boolean; optional.
+- Default: unstated.
+- Allowed values: schema type plus the normative behavior in this entry.
+- Normative source: [`spec/_.hint:399`](../spec/_.hint#L399).
+- Example: see the [public library manifest](https://github.com/neprel/git-a2a-demo-acme-lib/blob/main/a2amodule.yml) and [consumer manifest](https://github.com/neprel/git-a2a-demo-acme-app/blob/main/a2amodule.yml).
+
+Behavior and consequence:
+
+boolean, optional, default unstated. Declares whether outside agents are welcome. Changing it
+changes published contact policy only; the reference CLI does not enforce organisation identity.
+
+## `policy.intents`
+
+- Type: object; optional.
+- Default: unlisted intents route to `owner`.
+- Allowed values: schema type plus the normative behavior in this entry.
+- Normative source: [`spec/_.hint:431`](../spec/_.hint#L431).
+- Example: see the [public library manifest](https://github.com/neprel/git-a2a-demo-acme-lib/blob/main/a2amodule.yml) and [consumer manifest](https://github.com/neprel/git-a2a-demo-acme-app/blob/main/a2amodule.yml).
+
+Behavior and consequence:
+
+map intent → role. Which role answers which intent by default. Absent intents default to
+`owner`. Example: `change: spec` sends change requests to the specification agent rather than
+the coder — the pattern where engineers have full autonomy inside their repository and none
+outside it, and the manager owns the WHAT.
+
+Known values:
+
+| Known value | What the tool does | Consequence of changing it | Unknown value |
+| --- | --- | --- | --- |
+| `question` | Routes a request for explanation; defaults to role `owner`. | Selects contacts declaring `question` or `*`. | Accepted; policy and contacts can route any matching token. |
+| `change` | Routes a proposed behavior/API change. | Selects contacts declaring `change` or `*`. | Accepted; policy and contacts can route any matching token. |
+| `bug` | Routes a defect report. | Selects contacts declaring `bug` or `*`. | Accepted; policy and contacts can route any matching token. |
+| `review` | Routes a review request. | Selects contacts declaring `review` or `*`. | Accepted; policy and contacts can route any matching token. |
+| `incident` | Routes an operational incident. | Selects contacts declaring `incident` or `*`. | Accepted; policy and contacts can route any matching token. |
+| `*` | Acts as a contact fallback after exact intent matches. | Broadens that contact to unmatched intents. | Accepted; any other unknown token is an exact-match intent. |
+
+| Known value | What the tool does | Consequence of changing it | Unknown value |
+| --- | --- | --- | --- |
+| `owner` | Default routing target; identifies the agent that commits, merges, and releases. | Requests using the default route select a different binding. | Accepted and routed when policy names the same token. |
+| `maintainer` | Routes intents mapped to a maintainer. | Changes which bindings match those intents. | Accepted and routed when policy names the same token. |
+| `spec` | Routes specification, task, or sequencing ownership. | Changes which bindings match policy entries such as `change: spec`. | Accepted and routed when policy names the same token. |
+| `reviewer` | Routes review ownership. | Changes which bindings match review policy. | Accepted and routed when policy names the same token. |
+| `support` | Routes support ownership. | Changes which bindings match support policy. | Accepted and routed when policy names the same token. |
+
+## `policy.consumers`
+
+- Type: object; optional.
+- Default: none declared.
+- Allowed values: open vocabulary; see the known-values table in this entry.
+- Normative source: [`spec/_.hint:438`](../spec/_.hint#L438).
+- Example: see the [public library manifest](https://github.com/neprel/git-a2a-demo-acme-lib/blob/main/a2amodule.yml) and [consumer manifest](https://github.com/neprel/git-a2a-demo-acme-app/blob/main/a2amodule.yml).
+
+Behavior and consequence:
+
+object: `may` and `may-not`, lists of tokens from an open vocabulary (`read-surface`, `ask`,
+`open-issue`, `propose-change`, `commit`, `edit-spec`, `release`, …). Rendered verbatim into the
+consumer's roster block so an agent sees the boundary before it acts. Defaults when absent:
+`may: [read-surface, ask]`, `may-not: [commit]`.
+
+## `policy.notes`
+
+- Type: string; optional.
+- Default: none declared.
+- Allowed values: schema type plus the normative behavior in this entry.
+- Normative source: [`spec/_.hint:445`](../spec/_.hint#L445).
+- Example: see the [public library manifest](https://github.com/neprel/git-a2a-demo-acme-lib/blob/main/a2amodule.yml) and [consumer manifest](https://github.com/neprel/git-a2a-demo-acme-app/blob/main/a2amodule.yml).
+
+Behavior and consequence:
+
+string. Anything else consumers must know, verbatim.
+
+## `policy.consumers.may`
+
+- Type: array of string; optional.
+- Default: `[read-surface, ask]`.
+- Allowed values: schema type plus the normative behavior in this entry.
+- Normative source: [`spec/_.hint:453`](../spec/_.hint#L453).
+- Example: see the [public library manifest](https://github.com/neprel/git-a2a-demo-acme-lib/blob/main/a2amodule.yml) and [consumer manifest](https://github.com/neprel/git-a2a-demo-acme-app/blob/main/a2amodule.yml).
+
+Behavior and consequence:
+
+list of strings, optional, default `[read-surface, ask]`. Changing it changes the allowed actions
+rendered into consumer AGENTS.md rosters; the CLI reports the boundary but does not become an
+authorization service. Known values and unknown handling are in `vocabulary_consumers`.
+
+Known values:
+
+| Known value | What the tool does | Consequence of changing it | Unknown value |
+| --- | --- | --- | --- |
+| `read-surface` | Tells consumers they may read the published surface. | Adding/removing it changes the rendered boundary only. | Accepted and rendered verbatim; git-a2a does not enforce authorization. |
+| `ask` | Tells consumers they may contact an owning agent. | Adding/removing it changes the rendered boundary only. | Accepted and rendered verbatim; git-a2a does not enforce authorization. |
+| `open-issue`, `propose-change` | Tells consumers they may request owner-side work. | Adding/removing it changes the rendered boundary only. | Accepted and rendered verbatim; git-a2a does not enforce authorization. |
+| `commit`, `edit-spec`, `release` | Common `may-not` boundaries for owner-controlled changes. | Adding/removing one changes the prohibition shown in the roster. | Accepted and rendered verbatim; downstream agents must obey it. |
+
+## `policy.consumers.may-not`
+
+- Type: array of string; optional.
+- Default: `[commit]`.
+- Allowed values: schema type plus the normative behavior in this entry.
+- Normative source: [`spec/_.hint:459`](../spec/_.hint#L459).
+- Example: see the [public library manifest](https://github.com/neprel/git-a2a-demo-acme-lib/blob/main/a2amodule.yml) and [consumer manifest](https://github.com/neprel/git-a2a-demo-acme-app/blob/main/a2amodule.yml).
+
+Behavior and consequence:
+
+list of strings, optional, default `[commit]`. Changing it changes the prohibited actions rendered
+into consumer rosters; downstream agents remain responsible for obeying the declaration. Known
+values and unknown handling are in `vocabulary_consumers`.
+
+Known values:
+
+| Known value | What the tool does | Consequence of changing it | Unknown value |
+| --- | --- | --- | --- |
+| `read-surface` | Tells consumers they may read the published surface. | Adding/removing it changes the rendered boundary only. | Accepted and rendered verbatim; git-a2a does not enforce authorization. |
+| `ask` | Tells consumers they may contact an owning agent. | Adding/removing it changes the rendered boundary only. | Accepted and rendered verbatim; git-a2a does not enforce authorization. |
+| `open-issue`, `propose-change` | Tells consumers they may request owner-side work. | Adding/removing it changes the rendered boundary only. | Accepted and rendered verbatim; git-a2a does not enforce authorization. |
+| `commit`, `edit-spec`, `release` | Common `may-not` boundaries for owner-controlled changes. | Adding/removing one changes the prohibition shown in the roster. | Accepted and rendered verbatim; downstream agents must obey it. |
+
+## `dependencies[].id`
+
+- Type: string; optional.
+- Default: none declared.
+- Allowed values: pattern `^[a-z0-9][a-z0-9._-]{0,63}$`.
+- Normative source: [`spec/_.hint:469`](../spec/_.hint#L469).
+- Example: see the [public library manifest](https://github.com/neprel/git-a2a-demo-acme-lib/blob/main/a2amodule.yml) and [consumer manifest](https://github.com/neprel/git-a2a-demo-acme-app/blob/main/a2amodule.yml).
+
+Behavior and consequence:
+
+string. The dependency's `module.id`. Required after `add` (the CLI fills it from the fetched
+manifest); the lock is keyed on it.
+
+## `dependencies[].git`
+
+- Type: string; required.
+- Default: none declared.
+- Allowed values: minimum length 1.
+- Normative source: [`spec/_.hint:474`](../spec/_.hint#L474).
+- Example: see the [public library manifest](https://github.com/neprel/git-a2a-demo-acme-lib/blob/main/a2amodule.yml) and [consumer manifest](https://github.com/neprel/git-a2a-demo-acme-app/blob/main/a2amodule.yml).
+
+Behavior and consequence:
+
+string, required. The git URL (`ssh://`, `https://`, `git@host:path` scp form, `file://`).
+Stored exactly as given; credentials are never stored.
+
+## `dependencies[].ref`
+
+- Type: string; optional.
+- Default: the owner's `release.channel`, otherwise remote HEAD.
+- Allowed values: minimum length 1.
+- Normative source: [`spec/_.hint:479`](../spec/_.hint#L479).
+- Example: see the [public library manifest](https://github.com/neprel/git-a2a-demo-acme-lib/blob/main/a2amodule.yml) and [consumer manifest](https://github.com/neprel/git-a2a-demo-acme-app/blob/main/a2amodule.yml).
+
+Behavior and consequence:
+
+string. Branch, tag or commit to follow. Default: the dependency's `release.channel`, else the
+remote HEAD. Resolution: a 40-hex string is a commit; a full refname (`refs/heads/x`,
+`refs/tags/x`) is exactly that; a short name is resolved in git's own order — `refs/tags/<ref>`
+before `refs/heads/<ref>` — and an ambiguity is reported with the name chosen. A commit ref
+implies `track: locked`. Changing `ref`, `git` or `path` of an existing dependency is an
+ordinary edit (`git-a2a set`): identity is `module.id`, so the fetched manifest must carry the
+same id unless the consumer explicitly accepts a different one; every wired ecosystem follows
+the new source and pin together.
+
+## `dependencies[].path`
+
+- Type: string; optional.
+- Default: `.`.
+- Allowed values: minimum length 1.
+- Normative source: [`spec/_.hint:490`](../spec/_.hint#L490).
+- Example: see the [public library manifest](https://github.com/neprel/git-a2a-demo-acme-lib/blob/main/a2amodule.yml) and [consumer manifest](https://github.com/neprel/git-a2a-demo-acme-app/blob/main/a2amodule.yml).
+
+Behavior and consequence:
+
+string. Subdirectory containing the dependency's `a2amodule.yml` (monorepo). Default `.`.
+
+## `dependencies[].track`
+
+- Type: string; optional.
+- Default: `locked`.
+- Allowed values: one of `locked`, `floating`.
+- Normative source: [`spec/_.hint:494`](../spec/_.hint#L494).
+- Example: see the [public library manifest](https://github.com/neprel/git-a2a-demo-acme-lib/blob/main/a2amodule.yml) and [consumer manifest](https://github.com/neprel/git-a2a-demo-acme-app/blob/main/a2amodule.yml).
+
+Behavior and consequence:
+
+`locked` (default) or `floating`, a closed vocabulary described in `vocabulary_track`. Every mode
+still records one observed commit in the lock. Changing the mode rewrites supported native
+dependency forms; unknown values are rejected.
+
+Known values:
+
+| Value | What the tool does | Consequence of changing it | Unknown value |
+| --- | --- | --- | --- |
+| `locked` | Pins every supported ecosystem to the one commit recorded in the lock. | Switching to it replaces floating native refs with the resolved commit. | Rejected by validation. |
+| `floating` | Writes a branch/tag form where the adapter supports it while still recording the observed commit. | Switching to it lets native tools follow the declared ref independently. | Rejected by validation. |
+
+## `dependencies[].wire`
+
+- Type: array of string; optional.
+- Default: all matching detected ecosystems.
+- Allowed values: schema type plus the normative behavior in this entry.
+- Normative source: [`spec/_.hint:500`](../spec/_.hint#L500).
+- Example: see the [public library manifest](https://github.com/neprel/git-a2a-demo-acme-lib/blob/main/a2amodule.yml) and [consumer manifest](https://github.com/neprel/git-a2a-demo-acme-app/blob/main/a2amodule.yml).
+
+Behavior and consequence:
+
+list of ecosystems to wire, or absent for "every export that matches a manifest detected in this
+repository". An empty list means "record the dependency, wire nothing". When `wire` is absent
+and an export cannot be expressed in its ecosystem (the ecosystem has no git form for that URL,
+no subdirectory support, a floating ref it cannot store), the tool wires what it can, reports
+the rest as `not wired: <reason>` and `status` shows that ecosystem as `unwired`; it is an error
+only for an ecosystem named explicitly in `wire`. Wiring is repairable at any time
+(`git-a2a wire [ID]` re-applies every adapter from the lock, idempotently) — a half-wired
+dependency is a state the tool can always see and always fix, never one it hides.
+
+## Extension fields
+
+At every schema object that declares `patternProperties`, keys beginning with `x-` are
+extensions. The CLI preserves them; changing one changes only the extension consumer's
+behavior. A known object rejects every other unknown key.
+
+For an authoring sequence rather than field-by-field lookup, read the
+[owner's guide](authoring.md).