# Vercy model agent protocol

This is the common operating contract referenced by every meta-model
`AGENTS.md`. The model's local file supplies its identity, version, scope,
dependencies and any stricter rules. The nearest instruction applies, while
higher-level safety and authority continue to hold.

## Before using a model

1. Read the Dimension `AGENTS.md`, its installed-model lock and this model's
   `AGENTS.md`.
2. Verify the immutable specification URL, version and digest.
3. Read Bundle -> Layer -> Finding -> Questions -> Artifacts in that order.
4. Resolve child-model links, master systems, access exceptions and applicable
   patches before reading or writing instance data.
5. Keep the logical model independent from its file, database, API or MCP
   binding.

When the active Dimension policy grants `install-published-compatible`, resolve
the structural need through `https://ver.cy/api/v1/models/resolve/`, verify every
digest in the required published dependency closure, install each model with
`AGENTS.md` first, pin it and record typed links without asking the owner about
mechanics. Do not scrape the human catalogue and do not send instance or private
data to the API. Draft, todo, legacy, digestless or unresolved entries are never
autonomous installations.

If the API returns `202 accepted`, store the UUID and complete
`vercy-pending-model/v1` annotation in `registries/model-requests.yaml`. Continue
safe work with explicitly provisional fields and poll at the returned interval.
When the request is published, verify and install it, semantically migrate the
provisional data, validate and record the old-to-new paths. Never perform a
blind rename or claim the provisional structure was canonical.

## Whole-object coverage gate

Every subject model MUST assess five facets. Each facet is `required`,
`optional`, `not-applicable` with a reason, or `delegated` to a named child
model with a pinned reference.

Machine-readable contract: https://ver.cy/object-description-profile.yaml

1. **Identity and class**: stable identifiers, mastership, taxonomy, class
   boundaries, composition and instance-distinguishing features.
2. **Direct properties**: native properties of the object. Physical objects
   consider geometry, dimensions, material, mass, volume, density, colour,
   texture, pose, integrity, hardness, fragility and relevant limits, with
   units, tolerance and observation conditions.
3. **Recognition and observation**: signatures, confusing neighbouring
   classes, observation methods, measurements, confidence and evidence.
4. **Capabilities, behaviour and possible actions**: capabilities, current
   state, transitions, what may be done to or with the object, prerequisites,
   tools, effects, reversibility, permissions, constraints, hazards and failure
   modes.
5. **Context and evidence**: origin, maker, owner, location, trade,
   installation, use, maintenance, relationships, rules, events, provenance,
   uncertainty and time.

Do not force physical fields onto an organization, agreement or other abstract
object. Do not treat contextual history as a substitute for direct description
when the object is physical or observable.

## Populate

- Ask only questions needed for the present outcome, in small adaptive groups.
- Prefer authoritative master systems and direct observations. Preserve the
  distinction between verified fact, owner statement, inference, proposal and
  unknown.
- For each changing or observed property, record method, source, confidence,
  and an RFC 3339 timestamp containing seconds and a timezone.
- Use stable master-system identifiers when they exist. Otherwise create a
  Dimension-scoped identifier and retain identity-resolution evidence.
- Never invent answers. Turn unknowns into explicit questions or gaps.

## Extend or edit

- Editing instance data follows the Dimension's authority and lifecycle rules.
- Never mutate an immutable released specification. Create a declared patch,
  extension or new version and preserve the semantic diff and migration path.
- Reuse or delegate to a child model instead of widening a model beyond its
  boundary. Record why the dependency exists.
- Show the owner or reviewer the affected Bundle, Layer, Finding, Question and
  Artifact paths before a material change.
- Connecting already installed compatible models is routine maintenance when
  local policy grants it; changing their logical boundary remains a proposal.

## Validate

Validate schema and semantics, then check identifiers, mastership, units,
timestamps, references, access, provenance, uncertainty, facet applicability,
patch order and artifacts. A draft, unresolved critical conflict or failed
validation MUST NOT be represented as canonical or published.

## Retire or delete

Follow local retention and deletion authority. Prefer deprecation, successor
links and migration records. Preserve required audit events and provenance.
Deletion, publication, access expansion and irreversible external effects need
the authority explicitly declared in the Dimension; otherwise stop and ask.

## Completion report

Return the exact model and data locations, versions and digests, sources used,
questions answered, unknowns, validations, semantic changes, recorded events,
access implications and actions still awaiting authority.