> ## 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.

# Build on Asakiri

> What you need to read a course (learner app) or read and write one (creator app).

<Info>
  The on-disk format is canonical: `"format": "asakiri-course"`, `"formatVersion": 1`.
  Validate against the published
  [JSON Schemas](https://github.com/AsakiriLingo/asakiri-studio/tree/main/schemas/asakiri-course/v1)
  rather than reimplementing the parser, and read
  [Versioning and migration](/build/file-formats#versioning-and-migration) before you ship.
</Info>

These pages describe the concrete files and contracts, not just the domain model. If you
have not read the [Course data structure](/data-structure/overview) section yet, start
there for the concepts. This section covers the wire format.

## Two targets

<CardGroup cols={2}>
  <Card title="Learner app (read-only)" icon="book-open-reader">
    Load a course, resolve bindings, render fragments, play media, and grade responses.
  </Card>

  <Card title="Creator app (read + write)" icon="pen-to-square">
    Everything a reader does, plus editing files, enforcing the reference lifecycle, and
    validating before write.
  </Card>
</CardGroup>

## What to read, in order

<Steps>
  <Step title="Project layout">
    The [directory tree and manifest](/build/project-layout): how a course project is
    arranged and how `project.json` points at everything.
  </Step>

  <Step title="File formats">
    The [JSON for each entity](/build/file-formats): collections, records, assets, lessons,
    parts, compositions, and exercises.
  </Step>

  <Step title="Rich text">
    The [Tiptap document format](/build/rich-text), including the custom nodes that embed
    reusable content and media.
  </Step>

  <Step title="Resolving and rendering">
    The [learner-app contract](/build/resolving-and-rendering): turning bindings into
    values and grading each response.
  </Step>

  <Step title="Reader and writer">
    [How to assemble a reader or a writer](/build/reader-and-writer), plus versioning and
    what is still unspecified.
  </Step>
</Steps>

## What the format guarantees you

* **Every file is versioned.** `format` and `formatVersion` appear on every file, not just
  the manifest, so a file copied between courses still says what it is.
* **Identity is stable and separate from order.** Reordering a course rewrites lists of
  IDs and never changes the IDs themselves, so progress keyed on them survives.
* **Unknown content is preserved, not rejected.** A type you do not recognize is kept
  verbatim, so an older reader can open a newer course.
* **Answers never reference display text.** Grading refers to authored IDs or
  accepted-value bindings.

## Source of truth

Every page here tracks real code in the Studio repo: the `examples/courses/japanese-starter`
fixture, `src/core/course` (types, `resolve-binding.ts`, `parse-course.ts`), and
`src/platform/project-reading` and `project-writing` (the directory layout). When the code
changes, these pages should change with it.


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