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. Entity's internal model is canonical 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)
• 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).

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

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.

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.

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

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.

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 records discussion, decisions, and follow-ups in Markdown; it is not a third registry. Keep Project work products in 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. 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
• Projects and work context: projects
• The WebUI as a whole: webui
• Terms: glossary