@@ -22,24 +22,25 @@ Those names describe metadata found on historical Git objects only. Readers
 ignore legacy trailers, including malformed or conflicting values, and never
 use them to choose a schema.
 
-The old named entity CLI/API forms and named refs are historical compatibility
-paths. They may remain useful for addressing older entities, but they are not
-the document's type definition or content identity.
+Names remain how entities are addressed. A name is not the document's type
+definition and not its content identity, both of which live in the document
+itself.
 
 == Entity Identity and Refs
 
 `EntityId` is the OID of the complete bound document tree: the root containing
 exactly `schema/` and `value/`. It is not the OID of the publication commit and
-it is not a caller-selected alias. Both the embedded schema and encoded value
-therefore contribute to the identity. The canonical data ref is
-`refs/store/<kind>/<entity-id>`; named paths beneath the same kind are
-compatibility aliases and are excluded from the canonical entity index.
-
-The current `Kind` API exposes both layers. `put_entity`, `compile_entity`,
-`read_entity`, and `entity_reference` use the content-derived identity.
-`put`, `get`, `reference`, `entity_name`, `anonymous`, and related named forms
-are compatibility conveniences for ref-addressed callers. A named write may
-maintain an alias, but the name never becomes the entity's identity.
+it is not a caller-selected name. Both the embedded schema and encoded value
+therefore contribute to the identity.
+
+Identity is a derived value, not a ref layout. Data refs are
+`refs/store/<kind>/<name>`, and the name is whatever the caller chooses: the
+store attaches no meaning to it and advances it like a branch. Applications
+decide what names mean. An application that wants content-addressed storage
+selects `<entity-id>` as the name, which the store treats like any other;
+`put_entity`, `read_entity`, and `entity_reference` are the shorthand for that
+policy, and `compile_entity` derives the id for any document without publishing
+it.
 
 == Deletion and CLI Compatibility
 
@@ -55,16 +56,15 @@ The primary CLI form, `git store get <tree-ish>`, decodes a bound document from
 the tree it names. The hidden compatibility form, `git store get <kind> <name>`,
 reads a named ref and reports deleted entities differently from missing ones;
 revision suffixes such as `name~1` and `name@<revision>` address history.
-`git store rm <kind> <name>` publishes a tombstone over the canonical ref and
-any alias pointing at that publication. It does not hard-delete refs; repeating
+`git store rm <kind> <name>` publishes a tombstone over that name. It does not
+hard-delete refs, so the name's earlier publications stay reachable; repeating
 it reports `already deleted`, while an absent ref is an error. `get` reports a
-tombstone as deleted and an absent ref as absent.
+tombstone as deleted and an absent ref as absent. Names are independent:
+deleting one name does not affect another that addresses the same content.
 
-Writing the exact same bound content after deletion restores its original
-canonical ID by appending a normal value commit after the tombstone; aliases
-that pointed at the tombstone are restored atomically. Writing different
-content creates a new ID, leaving the old ID deleted. The CLI has no separate
-restore command; recreation and restoration are library write operations.
+Writing to a deleted name restores it by appending a normal value commit after
+the tombstone. The CLI has no separate restore command; recreation and
+restoration are ordinary write operations.
 
 == Trailer and Schema Compatibility
 
@@ -142,23 +142,23 @@ emit a success record. The current exit categories are:
 === Publication, CAS, and Identity
 
 `document publish <kind> <document-tree> --expected <absent|OID>` publishes a
-prepared bound document. With no `--alias`, the expectation applies to the
-canonical ref; with `--alias <name>`, it applies to that compatibility alias.
-The canonical ref, optional alias, and materialized per-kind index advance in
-one compare-and-swap batch. A stale expectation is a one-shot failure: the CLI
+prepared bound document under `--alias <name>`, defaulting to the entity's
+content-derived name when none is given. The expectation applies to that ref,
+and the ref and the materialized per-kind index advance in one compare-and-swap
+batch. A stale expectation is a one-shot failure: the CLI
 returns exit category `4` and does not retry. Objects written before a lost CAS
 may remain unreachable. A script owns retry, resume, and conflict policy.
 
 The complete bound document-tree OID is the content-derived `EntityId`, and both
-its schema and value contribute to it. The canonical ref is
-`refs/store/<kind>/<entity-id>`. Names are aliases, not identity. The persisted
-per-kind index under `refs/cache/` is a materialized cache of canonical refs;
-entity refs remain authoritative and reads can fall back when the index is
-missing, malformed, or stale.
-
-`entity delete <kind> <entity-id>` publishes a typed tombstone over the
-canonical ref and aliases/index atomically. It does not remove the ref. A
-repeated deletion reports `already_deleted`; an absent entity is distinct.
+its schema and value contribute to it. It is a derived value, available for any
+document that compiles, and is independent of where the document is published.
+The persisted per-kind index under `refs/cache/` is a materialized cache of the
+entity refs; those refs remain authoritative and reads can fall back when the
+index is missing, malformed, or stale.
+
+`entity delete <kind> <name>` publishes a typed tombstone over that ref,
+advancing it and the index atomically. It does not remove the ref. A repeated
+deletion reports `already_deleted`; an absent entity is distinct.
 
 === Script Boundary
 
 
@@ -30,8 +30,8 @@ $ git store get <document-tree> | jq .serves
 
 The positional `put <schema> [<value>]` form remains a convenient pure compile:
 it prints the bound document-tree OID and advances no ref. The hidden two-argument
-`put <kind> <name>` form is retained for old scripts and publishes a named
-compatibility alias. The explicit `value` and `document` commands make each
+`put <kind> <name>` form publishes the value under that name. The explicit
+`value` and `document` commands make each
 step addressable for a manually scripted migration.
 
 What landed is a real Git tree, not an opaque payload — `git ls-tree` and
@@ -54,7 +54,7 @@ $ git ls-tree refs/store/recipe/carbonara^{tree}:value
 $ git cat-file blob $(git rev-parse refs/store/recipe/carbonara^{tree}:value/serves)
 4
 
-$ git log --oneline refs/store/recipe/carbonara     # compatibility-alias history
+$ git log --oneline refs/store/recipe/carbonara     # this name's history
 9f50ef7 publish recipe
 15e425b publish recipe
 
@@ -119,9 +119,9 @@ git store                                   # list kinds
 git store put <schema> [<value>]            # pure compile; prints document-tree OID
 git store get <tree-ish>                    # decode a bound document
 git store check <tree-ish> <schema>         # validate a value tree against a published schema
-git store list [<kind>]   (alias: ls)       # kinds, or live entity aliases
-git store log  <kind> <name>                # commit OID + date per compatibility alias
-git store rm   <kind> <name>                # compatibility-name tombstone
+git store list [<kind>]   (alias: ls)       # kinds, or live entity names
+git store log  <kind> <name>                # commit OID + date per publication
+git store rm   <kind> <name>                # publish a tombstone over a name
 git store schema put <kind> [-F <file>]    # define/evolve a kind (else stdin, or -i)
 git store schema get <kind> [--at <commit>] [--legacy-leaves] # schema as JSON
 git store schema inspect <kind> --at <commit> [--legacy-leaves] # inspect publication
@@ -137,7 +137,7 @@ git store value decode <value-tree> --schema <tree-ish>
 git store document inspect <document-tree>
 git store document bind <value-tree> --schema <schema-tree>
 git store document publish <kind> <document-tree> --expected <absent|OID> [--alias <name>]
-git store entity delete <kind> <entity-id>   # canonical tombstone
+git store entity delete <kind> <name>        # typed tombstone over a name
 
 # Global layout options (defaults shown):
 git store --data-prefix refs/store --schema-prefix refs/schema <command>
@@ -200,8 +200,8 @@ tree; no kind lookup, schema-history guess, or trailer is consulted.
 `document bind <value-tree> --schema <schema-tree>` creates only the complete
 `{schema/, value/}` root tree. `document inspect <document-tree>` reports
 `bound`, `legacy_value_root`, or `malformed` without guessing. `document publish`
-then commits a prepared bound tree and updates the canonical ref, optional alias,
-and materialized index in one compare-and-swap batch.
+then commits a prepared bound tree and updates the named ref and materialized
+index in one compare-and-swap batch.
 
 `schema get <kind> --at <commit>` returns the schema snapshot at an explicit
 publication commit; without `--at` it returns the current snapshot. `schema
@@ -235,21 +235,23 @@ for the actionable diagnostic.
 ### Publication, identity, and deletion
 
 `document publish` requires `--expected absent` or `--expected <full-oid>`. With
-no alias the expectation applies to the selected data prefix's
-`<data-prefix>/<kind>/<entity-id>`; with `--alias` it applies to that alias. A
-stale expectation fails with exit category
+`--alias <name>` it publishes at `<data-prefix>/<kind>/<name>`; with no alias it
+publishes at the entity's content-derived name. The expectation applies to that
+ref. A stale expectation fails with exit category
 `4`, publishes none of the batch, and is **not retried**. Objects written before
 a lost CAS may remain unreachable; a script decides whether to retry, resume, or
 report the conflict. The CLI does not hide that policy.
 
 The bound document-tree OID is the content-derived `EntityId`, so both schema
-and value contribute to identity. The canonical ref is
-`<data-prefix>/<kind>/<entity-id>`. Caller names are compatibility aliases and
-are not identity or the source of truth. The per-kind index under `refs/cache/` is
-a materialized cache of canonical refs: entity refs remain authoritative, and
-readers can fall back to them when the index is absent, malformed, or stale.
-`entity delete <kind> <entity-id>` publishes a typed tombstone over the
-canonical ref and updates aliases/index atomically; it does not prune the ref.
+and value contribute to identity. It is a derived value, independent of where
+the document is published. Ref layout is application policy: an entity lives at
+`<data-prefix>/<kind>/<name>` for whatever name the caller picks, and naming it
+`<entity-id>` is one such choice rather than a rule the store imposes. The
+per-kind index under `refs/cache/` is a materialized cache of the entity refs:
+those refs remain authoritative, and readers can fall back to them when the
+index is absent, malformed, or stale. `entity delete <kind> <name>` publishes a
+typed tombstone over that ref and updates the index atomically; it does not
+prune the ref.
 
 ### Script boundary
 
 
@@ -29,7 +29,7 @@ use clap::{Parser, Subcommand, ValueEnum};
 use facet_git_tree::{Node, Schema, SchemaSchema, VariantKind, validate_with_schema};
 use facet_value::{VArray, VObject, Value, from_value};
 use gix_store::{
-    ApplyError, DeleteResult, DocumentInspection, Dynamic, EntityId, EntityState, Expectation,
+    ApplyError, DeleteResult, DocumentInspection, Dynamic, EntityState, Expectation,
     GixRefStore, Kind, Layout, ObjectId, PublishOptions, RefName, RefPath, RefPrefix, RefSegment,
     RefStore, RepoStore,
 };
@@ -1230,13 +1230,10 @@ fn entity_delete(
     entity_text: &str,
     format: OutputFormat,
 ) -> Result<()> {
-    let id: EntityId = entity_text.parse().with_context(|| {
-        cli_context(
-            ExitClass::Invalid,
-            format!("invalid canonical entity id {entity_text:?}"),
-        )
-    })?;
-    let result = store.dynamic(segment("kind", kind)?).delete_entity(id)?;
+    // Names are application policy: an entity may be published under a
+    // content-derived id or any other path, and either addresses it here.
+    let name = entity(entity_text)?;
+    let result = store.dynamic(segment("kind", kind)?).delete_name(&name)?;
     let (status, code, commit) = match result {
         DeleteResult::Deleted(entry) => ("deleted", "deleted", Some(entry.commit)),
         DeleteResult::AlreadyDeleted(entry) => {
@@ -1245,7 +1242,7 @@ fn entity_delete(
         DeleteResult::Absent => {
             return Err(cli_error(
                 ExitClass::NotFound,
-                format!("no entity {kind}/{id}"),
+                format!("no entity {kind}/{entity_text}"),
             ));
         }
     };
@@ -1254,13 +1251,13 @@ fn entity_delete(
         record.insert("status", status);
         record.insert("code", code);
         record.insert("kind", kind);
-        record.insert("id", id.to_string());
+        record.insert("id", entity_text.to_owned());
         if let Some(commit) = commit {
             record.insert("commit", oid_value(commit));
         }
         emit_record(format, record)
     } else {
-        println!("{status} {kind}/{id}");
+        println!("{status} {kind}/{entity_text}");
         Ok(())
     }
 }
 
@@ -198,13 +198,7 @@ fn store_get_list_and_remove() {
     let (out, _, ok) = run(path, None, &["ls", "recipe"]);
     assert!(ok);
     let listed: Vec<_> = out.lines().collect();
-    assert_eq!(listed.len(), 2);
-    assert!(listed.contains(&"carbonara"));
-    let older_canonical = listed
-        .iter()
-        .copied()
-        .find(|name| name.len() == 40)
-        .expect("older canonical identity");
+    assert_eq!(listed, ["carbonara"]);
 
     let (out, _, ok) = run(path, None, &["schema", "show", "recipe"]);
     assert!(ok);
@@ -244,7 +238,7 @@ fn store_get_list_and_remove() {
     let (out, err, ok) = run(path, None, &["ls", "recipe"]);
     assert!(ok, "list after rm failed: {err}");
     let listed_after_delete: Vec<_> = out.lines().collect();
-    assert_eq!(listed_after_delete, [older_canonical]);
+    assert!(listed_after_delete.is_empty(), "list after rm: {out}");
     assert!(
         !listed_after_delete.contains(&"carbonara"),
         "deleted alias must not list as live: {out}"
@@ -617,8 +611,7 @@ fn entity_names_may_nest() {
         .unwrap();
     assert_eq!(
         String::from_utf8_lossy(&refs.stdout).trim(),
-        "refs/store/recipe/2551a112682de0d7564849a0ab4d9d9a1bf6aaf1\
-\nrefs/store/recipe/italian/carbonara"
+        "refs/store/recipe/italian/carbonara"
     );
 }
 
@@ -1277,15 +1270,15 @@ fn composable_plumbing_supports_json_ndjson_and_explicit_cas() {
         path,
         None,
         &[
-            "entity", "delete", "recipe", &entity_id, "--format", "ndjson",
+            "entity", "delete", "recipe", "carbonara", "--format", "ndjson",
         ],
     );
     assert!(ok, "entity delete failed: {err}");
     assert_eq!(json_string_field(&deleted, "status"), "deleted");
     let (already, err, ok) = run(
         path,
         None,
-        &["entity", "delete", "recipe", &entity_id, "--json"],
+        &["entity", "delete", "recipe", "carbonara", "--json"],
     );
     assert!(ok, "repeated entity delete failed: {err}");
     assert_eq!(json_string_field(&already, "status"), "already_deleted");