# Naming Convention

## Doc File Names — PascalCase

Documentation files under `docs/model/`, `docs/command/`, and `docs/query/` **must** use PascalCase. The code generator derives the camelCase command/query name by lowercasing the first character of the file name.

| Doc type | File name format  | Example file       | Derived name    |
| -------- | ----------------- | ------------------ | --------------- |
| Model    | `{Entity}.md`     | `Product.md`       | —               |
| Command  | `{VerbEntity}.md` | `CreateProduct.md` | `createProduct` |
| Query    | `{VerbEntity}.md` | `GetProduct.md`    | `getProduct`    |

**Never use kebab-case** (`create-product.md`) — the generator will produce a broken name (`create-product`).

## Command Naming Convention

Commands use imperative `{verb}{Entity}` format. Use this canonical verb vocabulary when scaffolding commands.

## Canonical Verbs

| Verb               | Meaning                                             | Example                  |
| ------------------ | --------------------------------------------------- | ------------------------ |
| `create`           | Insert new entity                                   | `createItem`             |
| `update`           | Modify existing entity fields                       | `updateItem`             |
| `delete`           | Permanently remove entity (hard delete)             | `deleteItem`             |
| `activate`         | Enable entity (inactive → active)                   | `activateUnit`           |
| `deactivate`       | Soft-disable entity (active → inactive, reversible) | `deactivateUnit`         |
| `reactivate`       | Re-enable after deactivation                        | `reactivateItem`         |
| `assign...To...`   | Create a relationship between entities              | `assignRoleToUser`       |
| `remove...From...` | Remove a relationship between entities              | `removeItemFromTaxonomy` |
| `revoke...From...` | Remove permission/right (RBAC/security domain only) | `revokeRoleFromUser`     |
| `set`              | Configure a singular value or reference             | `setReferenceUnit`       |
| `move`             | Change position or parent in a hierarchy            | `moveTaxonomyNode`       |
| `log`              | Append-only audit/event record                      | `logAuditEvent`          |

## Choosing the Right Verb

- **`delete` vs `deactivate`**: Use `delete` only for permanent removal. Use `deactivate` for soft-disable where the record is preserved.
- **`remove...From...` vs `revoke...From...`**: Use `revoke` only in security/RBAC contexts (permissions, roles). Use `remove` for all other relationship unlinking.
- **`assign...To...`**: Always use `assign` to create relationships, never `add...To...`.
- **`activate` vs `reactivate`**: Use `reactivate` when the command specifically re-enables a previously deactivated entity and the distinction matters for business logic. Otherwise use `activate`.

## Banned Verbs

Do not use these — use the canonical alternative instead:

| Banned                  | Use instead               |
| ----------------------- | ------------------------- |
| `archive` / `unarchive` | `deactivate` / `activate` |
| `disable` / `enable`    | `deactivate` / `activate` |
| `add...To...`           | `assign...To...`          |
| `unlink`                | `remove...From...`        |

## Domain-Specific Verbs

If a feature requires a verb not in this table and the domain experts use it naturally (e.g., `approve`, `reject`, `cancel`, `close`, `submit`), it can be used. Document the rationale in the command doc.

## Feature Operation → Command Name

| Feature Operation    | Expected Command Doc | Notes                          |
| -------------------- | -------------------- | ------------------------------ |
| "Create X" / "Add X" | `createX`            | Never `addX`                   |
| "Update X"           | `updateX`            |                                |
| "Delete X"           | `deleteX`            | Hard delete only               |
| "Deactivate X"       | `deactivateX`        | Soft-disable (reversible)      |
| "Activate X"         | `activateX`          | Enable entity                  |
| "Reactivate X"       | `reactivateX`        | Re-enable after deactivation   |
| "Set default X"      | `setDefaultX`        | Singular value/reference       |
| "Assign X to Y"      | `assignXToY`         | Never `addXToY`                |
| "Remove X from Y"    | `removeXFromY`       | Generic relationship unlinking |
| "Revoke X from Y"    | `revokeXFromY`       | RBAC/security domain only      |
| "Move X"             | `moveX`              | Hierarchy position change      |
| "Log X"              | `logX`               | Append-only audit/event        |