// SPDX-License-Identifier: CC-BY-SA-4.0
= A2ML Profiles (a2ml/* namespace)
:toc:
:icons: font

Home of the profile definitions shipped by this repository, plus the
hash-pinned registry that indexes them. See `../SPEC.adoc` Sections 8 and 11
for the normative profile mechanism.

== Layout

[cols="2,3",options="header"]
|===
| Path | Contents
| `<namespace>-<name>/PROFILE.a2ml` | One profile definition (the single source
  of truth for that profile). Example: `a2ml-state/PROFILE.a2ml`.
| `REGISTRY.a2ml` | Verifiable index: one base record per profile, pinning its
  definition by sha256.
|===

== The seven `a2ml/*` profiles (6a2 family)

[cols="2,4",options="header"]
|===
| Profile id | Validates
| `a2ml/state`     | `STATE.a2ml` — current project state and progress
| `a2ml/meta`      | `META.a2ml` — architecture decisions / dev practices
| `a2ml/ecosystem` | `ECOSYSTEM.a2ml` — position in the ecosystem
| `a2ml/agentic`   | `AGENTIC.a2ml` — AI-agent permissions and constraints
| `a2ml/neurosym`  | `NEUROSYM.a2ml` — neurosymbolic / Hypatia config
| `a2ml/playbook`  | `PLAYBOOK.a2ml` — operational runbook
| `a2ml/anchor`    | `ANCHOR.a2ml` — canonical authority identity
|===

Each profile constrains only the five axes permitted by SPEC.adoc Section 8.2
(required sections, allowed directives, required directives, reference classes,
minimum attestation). All seven are non-executable validation bundles: they
raise strictness only and grant no capability.

== Declaring a profile in a document

A 6a2 document opts in with a single self-closing directive in its preamble:

----
@profile(id=a2ml/state)
----

== Verifying / regenerating the registry

The registry pins each definition by the sha256 of its exact bytes. To verify:

[source,sh]
----
sha256sum a2ml/profiles/*/PROFILE.a2ml
# compare each digest against the matching `hash:` line in REGISTRY.a2ml
----

When a definition changes, recompute its digest and update both the definition's
`version` and its registry entry. The registry is the verifiable index; a
consumer trusts a profile only when the computed hash equals the pinned hash.

== Adding a new profile

. Create `<namespace>-<name>/PROFILE.a2ml` with a single `@profile-def` block.
. Compute its sha256 and add a `@record` entry to `REGISTRY.a2ml`.
. If it is an `a2ml/*` profile, list it in SPEC.adoc Section 11.

The `a2ml/*` namespace is reserved for this repository. Downstream consumers
register their own profiles under their own namespaces, in their own repos.
