> For the complete documentation index, see [llms.txt](https://k-ai.gitbook.io/knowledge-ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://k-ai.gitbook.io/knowledge-ai/sources-and-ingestion/document-state-machine.md).

# Document state machine

Every document ingested by K-AI moves through a small set of states from registration to availability. State is visible in the indexing statistics of the instance page in the K-AI Studio portal. State transitions are durable and idempotent — retries are safe.

```mermaid
stateDiagram-v2
    [*] --> INITIAL_SAVED
    INITIAL_SAVED --> ON_CONTENT_EXTRACT
    ON_CONTENT_EXTRACT --> INDEXED
    INDEXED --> [*]
    INITIAL_SAVED --> PARSING_ERROR
    ON_CONTENT_EXTRACT --> PARSING_ERROR
    PARSING_ERROR --> INITIAL_SAVED
```

Three principal states — `INITIAL_SAVED`, `ON_CONTENT_EXTRACT`, `INDEXED` — are what a Consumer or Steward encounters. A handful of finer-grained transient states exist between extraction and graph write; they are not surfaced as user-facing milestones.

## INITIAL\_SAVED

The document has been registered with its source metadata: source URL, ACLs (mirrored from the upstream Document Repository), MIME type, last-modified date, and Owner / Authority pointers when known. Content has not yet been extracted.

Entering this state queues the document for indexation.

## ON\_CONTENT\_EXTRACT

Extraction is in progress: content is parsed (per MIME type), semantically structured, and embeddings are computed.

In this state the document is searchable on its metadata, but its content does not yet contribute to vector search or to the [Neural Semantic Graph](/knowledge-ai/the-k-ai-platform/neural-semantic-graph.md).

## INDEXED

Embeddings have been written to the per-instance vector store. Semantic graph nodes (concept, subject, actor, dependency) have been written to the instance's database. The document is fully available to Consumers — both for vector search and for [Neural Semantic Graph](/knowledge-ai/the-k-ai-platform/neural-semantic-graph.md) traversal.

`INDEXED` is the only terminal state for a healthy document. A re-indexation request moves the document back to `INITIAL_SAVED` and re-runs the pipeline; the result is deterministic for an unchanged source document.

## Failures & retries

Failures during extraction transition the document to `PARSING_ERROR`. The most common causes are: source unreachable at fetch time (expired credentials, deleted file, permission revoked upstream), unsupported or corrupted file format, or extraction timeout on very large files.

To re-queue documents in `PARSING_ERROR`, a user allowed to manage the instance clicks **Retry parsing errors** on the instance page of the K-AI Studio portal; it re-queues every document currently in error and is safe to repeat. Re-indexing the same document produces the same vectors and graph nodes, modulo content changes upstream.

## Observing state

A Steward or Engineer (DocOps) tracking indexation progress follows the indexing statistics on the instance page of the K-AI Studio portal.