---
title: "Company — Concepts, Entities"
description: "Share decision criteria through Concepts and map your company with Entities. Learn registration, proposals, permissions, hierarchy, and when to use Meetings."
---

# Company — Concepts, Entities

An aachat team holds shared context about the company itself, outside any individual piece of work (project). There are two layers. Concept's internal model (kind, semantic axes, revisions, reviews, links, similarity gate) is canonical in [concept-registry](/en/docs/concept-registry). Entity's internal model is canonical on this page.

| Layer | Content | Where in the WebUI | Detail |
|---|---|---|---|
| **Concept** | The team's agreed Visions, Issues, and Policies. Every agent and human reads them as premises for judgment | Team sidebar "Concepts" | [concept-registry](/en/docs/concept-registry) |
| **Entity** | A map of the persistent, concrete things that make up the company, decomposed to the level where building, improving, maintaining, or retiring each can be decided independently | Team sidebar "Entity" | Below on this page |

## Where to ask

**No dedicated place is needed.** Ask an agent in any project session as with any other request, or ask an outside agent working in a connected repo. Session agents use session authority; outside agents read the same projected YAML and use `aachat registry`, which submits with the signed-in human's Team role.

- **Read**: agents read published Concepts and current Entities and use them as premises for their judgment
- **Proposing Concepts**: agents register new Concepts, revisions, and links as **proposals**. A proposal stays pending, and **a human reviews it on the Concepts screen in the WebUI** to accept or decline. Only accepted Concepts become the team's decision criteria (see [concept-registry](/en/docs/concept-registry))
- **Entities**: agents can register and update Entities (normal kinds only — see below) directly from a session. Unlike Concepts, these take effect immediately, without a proposal-and-review step

In a connected repo, first require the Team projection in `aachat status` to be `healthy`, then read the two indexes, selected individual YAML, and matching Meeting bodies. Saving YAML is only a staged local edit; `aachat registry submit` is the explicit mutation boundary. The server applies the same authorization as a human WebUI action, so an Owner/Admin can submit sensitive Entity operations while a Member receives 403.

## Which layer to use

- A desired state, durable problem, or reusable decision policy → **Concept proposal**
- The concrete things that make up the company and where to focus improvement → **Entity**

Company context is both an input and an output of agent work. An agent working in a project returns findings as Concept proposals; once a human accepts them, every later session works on top of those criteria. This is how the company itself grows as an asset (the company-level version of the company assets flow in [concepts](/en/docs/concepts)).

## Entity model — kind, sensitive boundary, hierarchy

An Entity is an identifiable, persistent thing that concretely makes up the company. Entities form the Company map: they make it explicit what to build, improve, maintain, or retire, decomposed to a level where each improvement target can be selected independently.

**Entity stores no properties, evaluations, goals, KPIs, owners, or progress.** Those belong to Concept (decision criteria), Project/Session (work in progress), and Message/Shared Document (evidence and detail).

### What should be an Entity

Register something as an Entity when building, improving, maintaining, or retiring it can be decided independently. Create a child Entity only when separating it lets the company select that improvement target independently.

Before registering a new Entity, check existing Entities and add one only when the existing Entity is too broad as an improvement target. Goals, work, abstract responsibility areas, feature classifications, and implementation parts such as UI, APIs, Workers, CLI commands, or database tables are not Entities unless they are themselves concrete parts of the company that are improved independently.

### kind — 9 types

| kind | Note |
|---|---|
| `organization` | Normal |
| `offering` | Normal. A product or service |
| `media` | Normal. A channel or medium |
| `community` | Normal |
| `system` | Normal. An internal or external system |
| `facility` | Normal |
| `person` | **sensitive** |
| `partner` | **sensitive** |
| `agreement` | **sensitive** |

### The sensitive-kind boundary (important)

The three kinds `person` / `partner` / `agreement` **cannot be registered or changed by an agent**. If an agent attempts to register one, rename it, change its status, move it, or link a Concept to it, the server rejects the request. The rejection message is returned in Japanese regardless of the agent's own language:

> person / partner / agreement Entity の変更は human の操作が必要です。Project の human member に依頼してください。
>
> ("Changing a person / partner / agreement Entity requires a human action. Ask a human member of the project.")

Agents **can read** sensitive kinds — their name and structure are visible as part of the Company map. Writes are restricted to **human team Owners / Admins**; a regular human member is rejected as well. Don't infer an Entity's meaning or evaluation from what you read — only name, kind, status, and parent are stored.

### status — position in the company structure

`planned` / `current` / `retired` describe only the Entity's position in the company structure, not the progress of a piece of work.

- `planned`: planned as part of the company structure
- `current`: currently part of the company structure
- `retired`: no longer part of the company structure

**Hierarchy constraint**: an active Entity (`planned` / `current`) cannot be placed under a retired parent. Before retiring an Entity, its active children must be moved or retired first.

### Hierarchy (parent/child)

Entities form a tree. A parent is at most one Entity in the same team; self-reference, cycles, and cross-team parents are never allowed. Reparenting is done with a move operation. Don't represent more than one kind of structural relationship through parent (don't encode undefined relationships such as dependency, provision, or ownership into hierarchy or name).

### Concept link

An Entity can link to a published Concept with `realizes`. This is the only relation type in v1. Don't link to an archived Concept or one with no published content.

### Change history

Entity changes are recorded as append-only events: `registered`, `renamed`, `status_changed`, `moved`, `concept_link_added`, `concept_link_removed`.

## Register your first Entity

Open Entity in the Team sidebar and inspect the Entity map and existing names. A customer help center operated over time is a candidate for `media`; the work to launch it belongs in a Project. This example uses a Session agent. Replace `acme` with your Team slug and `acme/help-center` with a Project where the Session has collaborator/admin membership and coverage. Do not overwrite an existing file with the same name.

1. Run `chat registry refresh --all`, then read `aachat/teams/acme/entities/_index.yaml`. Follow its `file` references to the individual records you need.
2. If the Entity does not exist, save this complete file as `aachat/teams/acme/entities/help-center.entity.yaml`.

```yaml
format: aachat.team-entity/v1
id: null
name: Help center
kind: media
status: planned
parent: null
realizes: []
```

3. From the workspace root, check syntax, inspect the operation, and submit it.

```sh
chat registry check aachat/teams/acme/entities/help-center.entity.yaml
chat registry plan aachat/teams/acme/entities/help-center.entity.yaml --project acme/help-center
chat registry submit aachat/teams/acme/entities/help-center.entity.yaml --project acme/help-center
chat registry refresh --all
```

`check` validates locally. Confirm that `plan` describes a single registration before running `submit`. After a successful write, you can read the current Entity with its server-assigned ID and see it in Entity. Use the file referenced by the index thereafter; preserve its assigned ID and path. Registering a `planned` Entity is not evidence that the service has launched.

### Change a parent or connect a Concept

Refresh the existing `help-center.entity.yaml`, then change only `parent` to a relative reference to a real parent in the same directory, for example `parent: "./customer-services.entity.yaml"`. Repeat check → plan → submit → refresh, confirm the plan contains only a move, and inspect the new hierarchy in the UI. Use `parent: null` to return it to the root. Submit name or status changes separately from a move.

To connect a Concept, first locate its published file, then add one reference such as `"../concepts/customer-self-service.concept.yaml"` to `realizes`. Submit this operation separately too. These filenames are examples: copy actual filenames from the index. An Entity's `kind` is not an editable field after registration.

## Actors and permissions

| Operation | Session agent | Human Team Member | Human Owner / Admin |
|---|---|---|---|
| Register or change an ordinary Entity | With Project write permission and coverage | Allowed | Allowed |
| Change a sensitive Entity | Not allowed | Not allowed | Allowed |
| Propose a Concept, revision, or link | Proposal only | Proposal only | Propose and decide |
| Publish / decline a Concept, decide on links | Not allowed | Not allowed | Allowed |

When working as a human from a connected repo, first check that the Team projection is healthy in `aachat status`. Replace the commands in the Entity example with these. This CLI resolves the Team from the connection and file; it does not accept `--project`, `--team`, or `--via`.

```sh
aachat registry check aachat/teams/acme/entities/help-center.entity.yaml
aachat registry plan aachat/teams/acme/entities/help-center.entity.yaml
aachat registry submit aachat/teams/acme/entities/help-center.entity.yaml
aachat registry refresh --all
```

An outside agent using this CLI acts with the signed-in human's Team role. That is distinct from Session agent authority. A successful local plan does not guarantee server authorization.

## Where Registry and Meeting records live

Registry has two indexes: `concepts/_index.yaml` and `entities/_index.yaml`. Concepts describe decision criteria; Entities describe the things that make up the company. A [Meeting](/en/docs/meetings) records discussion, decisions, and follow-ups in Markdown; it is not a third registry. Keep Project work products in [Shared Documents](/en/docs/shared-documents).

A Session receives Meetings under `aachat/meetings/` as a read-only snapshot taken at startup. Registry YAML submission cannot create or correct them. Save Team-wide discussion as a Meeting; when part of it should become a reusable decision criterion, organize its evidence and propose a Concept.

## When a change does not apply

- `mixed_edit` means that one file combines multiple operations. Preserve your draft and split it into changes such as name only or parent only.
- For a sensitive-kind rejection, ask a human Project member to involve a Team Owner/Admin. Agent credentials cannot bypass this boundary.
- For a retired-parent or active-child error, change the order of moves and retirements to satisfy the hierarchy rules above.
- For stale state or an unknown result, follow [Registry recovery](/en/docs/concept-registry). Deleting YAML does not delete an Entity. Use `retired` to record that it is no longer part of the company.

Do not commit generated `aachat/teams/` or `aachat/.state/` into the workspace repository. Saving a file alone does not write to the server.

## Related pages

- Concept's types and lifecycle: [concept-registry](/en/docs/concept-registry)
- Projects and work context: [projects](/en/docs/projects)
- The WebUI as a whole: [webui](/en/docs/webui)
- Terms: [glossary](/en/docs/glossary)