Concept Registry — types and lifecycle of decision criteria

Of the two registries in Company, Concepts hold reusable team decision criteria. This guide explains how to propose a criterion with evidence, have a human review and publish it, and use it after adoption. Session agents read projected YAML under aachat/teams/<team>/concepts/, edit it, and propose changes with chat registry.

kind — Vision, Issue, and Policy

A Concept has one of three kinds. Choose it by the question the Concept answers. kind describes the content's role only; the semantic axes below (guidance_strength, etc.) are never derived automatically from kind.

Semantic axes — 6 axes

A Concept has 6 semantic axes independent of kind. YAML for a new Concept requires scope (domain + tags), abstraction_level, time_horizon, guidance_strength, and maturity. There is no automatic mapping such as policy = governing, and none is inferred from review counts either.

governing + established is a standard premise. governing + provisional must always be considered, checking sources or the latest review for high-impact decisions. governing + exploratory must always surface but must not be blindly followed. When governing Concepts conflict with each other, or an unresolved concern exists, don't pick a winner by score — read links, sources, and reviews and surface the unresolved conflict explicitly.

Revision model

A Concept is an immutable stack of revisions. The current revision is never rewritten directly; every change is recorded as a new proposed revision.

• A revision's status is one of pending / published / declined
• A Concept can have at most one pending revision at a time. A new proposal cannot be submitted while one is already pending
• Only humans (a team's Owner/Admin) can publish or decline. Agents can only propose
• A decline requires a reason. The next session should read that reason and calibrate its criteria before deciding whether to re-propose
• Once created, a revision's content is immutable. Even changes to wording, sources, scope, or time horizon are recorded as a new revision

Title is capped at 80 characters and description at 300 — they are an entry point, not a summary; the detailed evidence is read through sources (below).

Reviews

Both pending and published revisions can carry two kinds of review: endorse and concern. A concern requires a comment (an endorse's comment is optional), and can be resolved with a resolution note. A published revision may still be read as a premise even with an open concern, but for decisions that depend heavily on that Concept, check the current revision's comments with aachat_concept_reviews and surface that the concern exists. Post a review with aachat_concept_review; projected concepts/_index.yaml carries only open_concern_count.

Links between Concepts

Concepts connect to each other through 8 directional relation types.

Links also have a lifecycle: candidate / accepted / retired / rejected. An agent can propose a link as a candidate by editing a Concept YAML link and running chat registry submit, but it counts as a valid relationship for the Concept Map or for judgment only once accepted. Only humans (a team's Owner/Admin) can accept, reject, or retire a link.

When a published Concept would mislead future decisions, an agent can send an archive proposal to the Review queue with aachat_concept_removal_propose. For an accepted Link, remove it from the Concept YAML and run chat registry submit --reason to propose retirement. The Map does not change until a human accepts it, and history remains as an archived Concept or retired Link.

Similarity gate on proposal

chat registry submit for a new Concept automatically checks it against existing Concepts before registration. If a similar Concept is found, the proposal is not registered and similar_found is returned instead.

• A similar published Concept — a decision criterion already exists. Withdraw, or switch to a link proposal or a review if there's a relationship. If the evidence reveals a durable gap, consider an issue + a contradicts link
• A similar declined Concept — a human already rejected this. Read the decline reason (status_reason) and don't repeat the same proposal
• A similar pending Concept — someone else's revision proposal is awaiting review. Don't submit a duplicate
• A match against a pending or declined Concept the caller lacks permission to see returns no content or ID — only hidden_match_count
• Only when the proposal is genuinely something different, resubmit with the returned proceed_token to register it anyway

Sources

A proposal is submitted with sources attached. There are 5 kinds.

For a Session agent proposal, at least one source must belong to the Project selected by --project; other Project sources must also be in the same Team and Session coverage. A source's availability is shown as one of accessible / restricted / unavailable; don't guess at the content of a restricted source. unavailable means the source cannot currently be resolved; check for deletion or changes such as Session coverage.

Archive / restore

A Concept can be archived and restored. This is a WebUI/human-only operation and is not exposed as an agent-facing MCP tool. Don't create new links to an archived Concept or one with no published content.

Free placement on the Concept Map

The WebUI's Concepts screen has a map view. A card's position (free_position) can be moved by a human, or by an agent editing Concept YAML and running chat registry submit. Placement is shared soft context: proximity between Concepts can be a hint worth considering, but when it conflicts with sources, typed links, or semantic fields, those take precedence. Don't assert a relationship that appears only in placement as fact — if it looks important, treat it as a candidate for a link proposal instead.

Propose a Concept with evidence

Open Concepts in the Team sidebar and inspect existing Concepts and the Review queue. If the policy or a pending revision already exists, read it and its reviews before proposing a duplicate. Check the Company permissions table first. The following steps are for a Session agent with Project write permission and coverage.

This example assumes that the acme/help-center Project has docs/research/support-friction.md, recording evidence that users could not find answers and explaining the proposed improvement. Replace the Team/Project, document kind, and document ID with real ones, read that evidence, and adapt the proposal. Do not submit a fictional source unchanged.

Run chat registry refresh --all and read concepts/_index.yaml. Then save this complete new file as aachat/teams/acme/concepts/customer-self-service.concept.yaml.

format: aachat.team-concept/v1
id: null
kind: policy
title: Make answers easy to find
description: Prefer clear, searchable help before adding support channels.
scope:
  domain: product
  tags:
    - support
abstraction_level: directional
time_horizon: enduring
expires_at: null
guidance_strength: guiding
maturity: provisional
position: null
sources:
  - kind: shared_document
    project: "acme/help-center"
    document_kind: research
    doc_id: support-friction
restricted_source_count: 0
links: []

id: null means a new registration. New Concepts require position: null and links: []; change position and links separately after publication. A time horizon other than enduring needs a future expiry as a quoted RFC3339 timestamp. Supply 1–20 sources; a new Concept has restricted_source_count: 0.

From the workspace root, run these commands in order.

chat registry check aachat/teams/acme/concepts/customer-self-service.concept.yaml
chat registry plan aachat/teams/acme/concepts/customer-self-service.concept.yaml --project acme/help-center
chat registry submit aachat/teams/acme/concepts/customer-self-service.concept.yaml --project acme/help-center
chat registry refresh --all

check validates local YAML; it does not guarantee that a source exists or that the server will authorize the operation. Confirm that plan contains the intended single operation. After submit accepts the proposal, a Team Owner/Admin reads its evidence and changes in the Concepts Review queue, then publishes it or declines with a reason. Acceptance of a submission is not adoption of its content.

Projected YAML represents published current content only. Do not resubmit because the file returns to its old content or a new pending proposal's text does not appear in the index. Check the receipt and Review queue. After human publication, refresh and confirm the current content matches the adopted revision.

Separate revisions from position changes

For an existing Concept, refresh the file referenced by the index's file field. To improve its description, edit description, preserve its existing ID and other required fields, and repeat check → plan → submit. Changes to meaning, sources, or scope create a new pending revision. If a revision is already pending, check its review outcome first.

To change position only, replace position: null or the current position in the existing file with this block, leaving every other field unchanged. Do not save this fragment as the entire file.

position:
  x: 240.0
  y: 120.0

Repeat check → plan → submit → refresh. A position-only change applies directly; it does not approve the Concept's meaning. Coordinates must be finite, with each axis between -1000000 and 1000000. Editing meaning and position together produces mixed_edit, so submit them separately.

Propose as a human from a connected repo

Check that the Team projection is healthy in aachat status, then use these commands with the same YAML.

aachat registry check aachat/teams/acme/concepts/customer-self-service.concept.yaml
aachat registry plan aachat/teams/acme/concepts/customer-self-service.concept.yaml
aachat registry submit aachat/teams/acme/concepts/customer-self-service.concept.yaml
aachat registry refresh --all

This CLI has no --project or --proceed-token. The repo connection determines the Team; the server checks access to the Projects named in sources. Even an Owner/Admin's semantic submission is a proposal; publication is a separate decision. Clearing position to null is unsupported in the outside CLI. Removing an accepted Link also differs from an agent's retirement proposal: it is a human retirement operation requiring Owner/Admin and --reason.

Follow sources and reviews

Open Sources from a Concept Map card's menu to follow its evidence. Open the card's detail to inspect current content, reviews, and History. Distinguish pending content in the Review queue from the currently published content. For example, if the policy above is published but has an open concern that some languages remain hard to search, do not restate it as proof that all users can help themselves.

restricted means you lack access to that source. Ask an authorized human to check the necessary evidence; do not infer its contents. For unavailable, the source cannot currently be resolved. Check for deletion or changed Session coverage and consider a revision with accessible evidence. The WebUI requires access to all sources before proposing a revision. In a Session agent YAML revision, preserve restricted_source_count and edit only visible sources. The server inherits restricted sources and checks the combined limit of 20. The index's open_concern_count does not explain concerns, so read the comments. Expiry excludes content from current decision context; it does not delete its adoption history.

Both the Concept source model and Registry YAML sources accept five kinds: shared_document, session, repository, external, and human_decision. It does not accept project_message. Inspect omitted sources in the WebUI instead of reconstructing them in the projection. For Session agent proposals, external or human_decision sources alone do not satisfy the Project-source requirement.

YAML constraints and recovery

Use UTF-8 and LF newlines, without unknown or duplicate keys, tabs, anchors, aliases, merge keys, or explicit tags. Preserve quoted UUIDs, timestamps, and file references. Use a meaningful lowercase ASCII slug and id: null for a new record; never rename an existing ID or assigned path. Do not edit generated _index.yaml. Each submit handles one file and one operation. Saving is not a server mutation, and deleting a file does not archive a Concept.

For a similarity-gate retry, use the actual token returned by the command.

chat registry submit aachat/teams/acme/concepts/customer-self-service.concept.yaml --project acme/help-center --proceed-token '<returned-proceed-token>'

Only for a conflict, preserve any needed local draft elsewhere before explicitly discarding changes to the affected file.

chat registry refresh aachat/teams/acme/concepts/customer-self-service.concept.yaml --discard-local

This discards local edits. Read current content, reapply only the intended differences, then repeat check → plan → submit. In a connected repo, replace chat with aachat. An ordinary refresh does not silently overwrite dirty files. For an unknown-result retry, the CLI uses retained inflight information to reconcile server state first; do not edit or delete that file or internal state.

Related pages

• The two-layer overview and how to ask: company
• Entity's types and lifecycle: company
• Terms: glossary