Getting your content AI-ready: a file-source readiness checklist

Who this is for. A client administrator preparing a folder of documents so Knowledge Hub can turn them into a clean, AI-ready knowledge base. You do not need to be a developer to follow it. This is the v1 checklist and it covers file sources only (folders of documents). Database sources and a point-and-click onboarding screen are coming in a later release — see What v1 does not yet cover.

{69.8} READINESS artefact for ID-69 (client corpus & AI-readiness onboarding model). This document is the client-readable contract — the obligations a client must meet before their content is staged. It is deliberately distinct from the internal ingest mechanics, which live in TECH.md.

Status: v1 readiness contract. Authored 01/06/2026 (S292 implementation wave).
Language: UK English. Dates are DD/MM/YYYY.

In one sentence

Hand us a folder containing only the documents you want in your knowledge base, in one of the supported file formats, with a stable folder layout — and we turn each document into a clean, searchable, AI-ready record.

1. The readiness checklist

Work through this before your content folder is staged for ingest. Each item is something you (the client) own; the platform does the rest.

Only the right documents are in the folder. The folder should contain the content you actually want an AI assistant to draw on — not a wholesale dump of everything on a shared drive. Content enters the knowledge base once, in canonical form. Think “the documents I would hand a new colleague to get them up to speed”, not “the entire file server”.
Every file is in a supported format (see Supported formats). In v1 the pipeline stops with an error the first time it meets an unsupported file — so a single stray file of the wrong type will block the run. There is no automatic “skip the ones I can’t read” behaviour in v1.
Each document is in “AI-ready canonical form” (see What “AI-ready canonical form” means).
The folder layout is settled and will not be reorganised. The location of each file inside the folder is part of its identity. Moving or renaming files after ingest has consequences (see Why the folder layout must stay stable).
The base folder path is fixed. The single top-level folder that holds your corpus must keep the same location. Changing it re-forks every document’s identity and breaks workspace mapping (see Base-path stability).

2. Supported formats

In v1 the pipeline accepts these file types and only these:

Kind	Extensions
Documents	`.pdf`, `.docx`, `.xlsx`
Web pages / HTML	`.html`, `.htm`
Plain text / Markdown	`.md`, `.markdown`, `.txt`

Anything outside this set is not ingested. Crucially, in v1 an unsupported file does not get quietly skipped — the run raises an error and stops. That is why the checklist asks you to stage a clean folder: one .png, .zip, or .pptx left in the folder will halt the whole ingest until it is removed.

What is coming later (not in v1). A future release will change this from “raise and stop” to “skip the unsupported file and carry on, recording what was skipped”. v1 deliberately does not add that yet — see What v1 does not yet cover.

3. What “AI-ready canonical form” means

“AI-ready canonical form” is the shape a document needs to be in so that an AI assistant can use it reliably. In practice, for each document:

It is the real, current version — not a superseded draft, not a duplicate copy of another file. One document, one source of truth. (The platform will de-duplicate where it can, but you save everyone time by not staging three near-identical copies of the same policy.)
The content lives inside the file, not in the filename or folder name. The platform reads the contents of each document. A file called final_v3_USE_THIS_ONE.pdf with the real text inside is fine; an empty file whose only information is its name is not.
It is a self-contained document. Scanned-image-only PDFs with no extractable text, password-protected files, or files that are really shortcuts or links to somewhere else are not AI-ready.
It is in a supported format (see above). If your source is, say, a PowerPoint deck or an email export, convert it to one of the supported formats first.

The platform takes each AI-ready file and produces a clean canonical record from it — extracting the text, classifying it, and making it searchable. You do not need to tag, label, or assign documents to a particular area yourself; the platform handles classification, and your team assigns documents to workspaces afterwards inside the application.

4. Why the folder layout must stay stable

Each document’s identity is derived from where it sits inside your corpus folder (its path relative to the base folder). This has two consequences you need to know:

Stable path = stable record. As long as a document stays in the same place, re-running the ingest after you edit its contents updates the same record. Your edits flow through; nothing is lost; any workspace associations the document already has are preserved.
Moving or renaming a file forks its identity. If you move policies/leave.md to hr/leave.md, the platform treats the moved file as a brand-new document, not the same one in a new place. The old record is left behind and the moved file comes in fresh. This is why the checklist asks you to settle the folder layout before ingest and avoid reorganising it afterwards.

If you do need to reorganise, treat it as a deliberate change and tell your Knowledge Hub contact, so the old records can be cleaned up rather than left as orphans.

5. Base-path stability — the operator obligation

There is one top-level folder that holds your whole corpus (the “base path”). Keeping that base path stable is a required part of the readiness contract:

If the base path changes, every document’s identity changes. Because each record’s identity is built from its path relative to the base folder, moving or renaming the base folder re-forks every document at once — the entire corpus comes in as new records. Treat the base path as fixed for the life of the corpus.
The base path also anchors your workspace mapping. The file that tells the platform which workspace each part of your corpus belongs to lives inside the base folder, at .kh-workspace-map.json. If the base path drifts, that mapping can no longer be found and resolution breaks. So base-path drift is a double hazard: it forks identities and breaks workspace mapping.

The physical storage of the corpus folder is managed for you by the platform (this is owned by a separate piece of platform setup). Your obligation is simply: once your corpus is staged, do not move or rename the base folder.

What v1 does not yet cover

To set expectations clearly, the following are explicitly out of scope for v1 and are planned for a later release:

Database sources. v1 covers folders of files only. Connecting a database as a content source is a v1.1+ capability.
A point-and-click onboarding screen. v1 is this written contract plus the operator-supported staging process — there is no self-service “connect your content folder” user interface yet. That onboarding experience is deferred to a later release.
Automatic skipping of unsupported files. As noted above, v1 stops on the first unsupported file. The “skip and continue” behaviour, and any include/exclude filtering of what gets ingested, are deferred — v1 relies on you staging a clean folder of supported files.

Quick reference

You provide	The platform does
A clean folder of supported files	Reads, extracts and cleans each document
AI-ready, current, self-contained documents	Classifies and makes them searchable
A stable folder layout and base path	Keeps each record’s identity stable across updates
(Inside the app) assign documents to workspaces	Preserves those associations across re-ingest

Changelog

Date	Session	Note
01/06/2026	S292	`{69.8}` client-readable file-source readiness contract authored per PLAN. Covers the readiness checklist (BI-10), base-path stability + identity-fork consequence (BI-7), and clean-staged-folder discipline / raise-on-unsupported (BI-9). Database sources and onboarding UX explicitly deferred to v1.1. File sources only; no UI.