Repository documentation

Literate AI user guide

Literate AI is a release-engineering and SDLC harness: it templates new repositories, converts existing ones, and runs an evidence-gated dev workflow through verify, rebuild, and versioned release. Readable Component specifications remain authority; generated source is disposable. This guide separates what an operator does from the lower-level framework contracts a product integrates.

“Literate” keeps Don Knuth's human-first idea without imposing a notebook or tangled source format: readable intent leads, while exact machine identities make the explanation executable and auditable. The diagrams in this guide are reading maps for that relationship, not extra framework layers.

Architecture at a glance

flowchart LR
    subgraph P[Project authority]
        C[Component behavior]
        F[Selected Flavors]
        S[Pinned skills]
        W[Workflow + routing]
        D[Content-pinned lifecycle driver]
        N[Linked reviewed documentation]
    end
    subgraph K[Framework core]
        R[Resolve exact identities]
        L[Orchestrate guarded lifecycle]
    end
    subgraph A[Injected adapters]
        M[Coding CLI]
        H[Host toolchains]
        P1[Cache + publication]
        B[Strict CycloneDX validation]
    end
    C --> R
    F --> R
    S --> R
    W --> R
    D --> R
    N --> R
    R --> L
    L --> M
    L --> H
    L --> P1
    L --> B
    L --> T[Generated checks + passing receipt]

The project artifacts decide intent and policy inputs. The provider-neutral core resolves and enforces them; adapters are the only layer that talks to coding agents, host compilers and runtimes, filesystems, or publication destinations.

Choose a path

Start with Getting started for a runnable tour, then use the framework flow for the one-page golden path and the canonical project layout for the repository taxonomy. The sections below are task-specific follow-ons.

Use current features and release posture when you need the version-aware answer: main is the 1.4.0 development line, 1.3.0 is the latest published release, and 1.3.1 has its own patch-release gates. The visual labs provide the shortest playful route from one Component to a multimedia Component DAG.

For a presentation-ready view of a project's effective repositories, Components, Flavors, skills and exact source bindings, generate the built-in HTML repository explorer. It is a provenance-bound authority-graph view, not a general source-code browser.

I have an existing source tree

1. Install Literate AI.
2. Run litai doctor, then inspect litai onboard adopt PATH. Re-run it with --apply --acknowledge when the catalog can wrap the tree. Follow skills/agent/convert-project/SKILL.md after the harness stamps the taxonomy. See Getting started.
3. Inverse source to specification remains a later authority-transfer tool for promoting original source to spec-led release authority; it is not the adoption path.

I am designing a Component

1. Start with Getting started and the framework flow, then read core concepts and layered Components.
2. Write readable, factored specifications, then define identity and exact versioning.
3. Keep OS, GPU, language, and toolchain differences in Flavors and target profiles.
4. Select model groups, selectors, and generation workflow.
5. Keep generated checks, verifier acceptance, and the current receipt separate by following the framework test flow.
6. Decide how caches, packages, and publication work.
7. Preserve the complete CycloneDX SBOM and dependency graph.
8. Apply source trust and build security before any build.
9. Release the exact repository authority through the project release protocol.

I am maintaining a release line

1. Read the Release Policy.
2. Keep ordinary work on writable main; classify every pull request with exactly one Literate-AI-Release: major.minor or Literate-AI-Release: none line.
3. Use LitAI release commands for state transitions, RC tags, backports, checks, and publication. Treat forge branch protection as a separate setting that should mirror the policy, not as something LitAI silently configures.
4. Inspect worktrees and pull requests before using the marker-based, dry-run-first peer-work garbage collector.

I am integrating the framework

1. Read the CLI and configuration reference to understand the current supported operator surface.
2. Run the conformance samples.
3. Read product integration, migration, and rollback for the application-specific adapter and compatibility-reader boundary.

Reference

• Current features and release posture
• Progressive visual labs
• HTML repository explorer
• Troubleshooting
• Glossary
• Repository documentation index
• JSON Schemas

Current boundary

The installed litai catalog is an SDLC: onboard (doctor, onboard create, onboard adopt, status), lower-level project mutation (init, init --convert, update, reparent), the dev workflow (verify, lock, plan, rebuild, build/test/run, package), and versioned release. Authority, operator, and inverse spec * commands stay available but are not the product front door. --target selects a generation/Flavor profile, while --worker selects local or command execution through a typed dispatch contract. litai rebuild runs a content-pinned project lifecycle driver; project-specific native builders remain adapters rather than hidden policy in the neutral CLI. Product-specific UIs, domain policy, native adapters, and operator workflows are not framework commands.

Today, litai rebuild selects the lifecycle binding declared by the project. A Standard-bound project runs the provider-neutral per-Component application service with source-only candidates, typed artifact assembly, accepted-source cache custody, and an aggregate receipt. This repository declares a content-pinned external driver whose samples still use the host lifecycle facade. Complete sample and qualification migration, link/package actions, and root-integration acceptance remain delivery work. See the framework flow for the explicit boundary map.

The constraint classification decision separates framework invariants from current repository policy and future delivery claims. In particular, the high-level lifecycle is not a claim that every stage has an independent mutable CLI command or that the included runners form a hardened OS sandbox.