> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asakiri.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Reference lifecycle

> How live references, usage tracking, deletion, and validation behave.

References between the outline and content are **live by default**. Editing a record
updates every place it is used. To keep "updates everywhere" safe, Asakiri tracks usage
and refuses silent cascades.

## Usage tracking

Every content record, field, item, and asset has a derived **usage list**. The usage
graph is computed from project content and may be cached. It is a derived view, not an
independently editable source of truth.

## Deletion and detachment

* Referenced entities **cannot be silently deleted**. The author must replace references,
  detach usages, or explicitly leave them broken.
* **Detaching** text or structured content creates an intentional
  [literal](/data-structure/bindings#detachment) snapshot in the lesson or exercise.
* Detaching presentation from a record does **not** duplicate binary media. Media stays
  referenced by asset ID unless the author imports a distinct file.

## Validation

A validation pass reports missing records, fields, repeated items, and assets whenever a
project opens. The bundled `japanese-starter` fixture is checked in CI with
`pnpm check:example`.

## What is settled vs deferred

<Note>
  Both the **shape** of the model and the **on-disk format** are settled. The format is
  version 1, published with JSON Schemas: see [Project layout](/build/project-layout) and
  [File formats](/build/file-formats).
</Note>

Still deliberately undecided:

* schema-template format and custom-field constraints;
* whether record changes need revision history beyond git;
* query-based runtime exercise generation;
* packaging rules for the separate learner application.

These choices stay behind repository and resolver ports, so they do not leak into feature
code or Tiptap documents. Treat content tables as authoring views, not as a rule that one
table equals one file: a collection is one file listing its records, and each record is a
file of its own.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.