Organizing Base Items

Open Admin → Knowledge Bases and select a base to inspect and maintain its items. The route requires the bases.view capability; creating, editing, importing, optimizing, and moving content requires bases.write, while deletion requires bases.delete.

Understand the screen

In the header, people with write permission can edit the base name and description inline. Press Enter or leave the field to save; Escape discards the local change. The limits are 100 characters for the name and 500 for the description.

The Items, Chunks, and Tokens indicators total every loaded item, including items that are pending, processing, or in error. They measure registered volume, not only content available to the agent.

The desktop table and mobile cards show name, preview, type, size, status, and creation date. Visible types are Text, File, and Crawl. Use Import CSV, Export CSV, or Add Item at the top according to the task.

Search and open content

Search by name or content filters the items already loaded by the screen locally, with a 200-character query limit. The filter compares the item name and content field. For processed files whose text exists only in private chunks, list search may find the name but not necessarily a phrase inside the document.

Open a row’s three-dot menu to see its available actions. A read-only profile gets a direct View button. The view dialog prioritizes the active optimizer revision and, when needed, rebuilds a file’s text from its private chunks. Use Copy content there and, for crawl items with a URL, Open original.

Track processing

State	Meaning	What to do
Pending	The item is waiting for processing.	Wait before testing retrieval.
Processing	Extraction, chunking, or indexing is in progress.	Watch the percentage and do not create a duplicate.
Processed	Indexing finished and the item can participate in agent search.	Validate it with real questions.
Error	Ingestion failed.	Check the source; edit a text item or remove and recreate a file.

Only Processed is ready for retrieval. Saving a text item returns it to Pending and starts another indexing pass. The processor writes new vectors before removing the old ones; this avoids a window with no index, but the previous content may remain retrievable until the switch finishes.

Add or edit items

Add Item opens three tabs: Text Block, File, and Website. Import CSV creates multiple text items. See Uploading Documents for formats, limits, crawling, and imports.

In a row menu, Edit appears only for items whose source is Text. The editor lets you change the name and Markdown content, up to 100 characters for the name and 100,000 for the content. It warns before leaving with unsaved changes. To change the source of a File item, remove it and upload the correct document; crawl items are managed through their crawl.

Improve items with the optimizer

SquadOS evaluates item structure and may display Can be improved or Hard to query. No badge may mean that the item is ready, has already been optimized, or that evaluation did not finish; always validate through actual agent retrieval.

With bases.write, open the menu and select Optimize with AI. When more than one item needs improvement, a notice also offers Yes, optimize to run the batch or Not now to dismiss it. If the plan does not include knowledge_optimizer, the action leads to See plans.

Evaluation identifies structural issues. Transformation reorganizes content, reduces noise, and may add search vocabulary without sending the entire body to the auxiliary model: it receives only a structural skeleton and limited samples. The platform pays for this use, and it does not debit organization credits.

For a PDF, the optimizer works on the text that indexing extracted from the document, not on the original file. The item must therefore be Processed: while it is pending or processing, the action reports that the item is still being processed. If the PDF has no indexed text, for example because indexing ended with Error, the action reports that it could not find the item’s content. In that case, remove the item and upload the document again before optimizing.

After the operation, review the report for chunks, removed fields, vocabulary, and misaligned rows. Go back to original is available only in that current report. Reloading the page discards the report, and batch optimization retains only the last completed item’s report; review and decide about reverting before leaving the screen.

Select, move, and delete

Select checkboxes to open the selection bar. Move Selected asks for a destination base in the same organization. Delete Selected appears for people with bases.delete and requires confirmation. For a single item, use Remove in the row menu; the same rule applies.

Moving changes the items’ database association first, then updates their vectors. If that second step fails, the current UI may still report success. After moving, open the destination base and test a question that depends on the content; if the result still comes from the previous base or does not appear, stop further moves and request technical verification.

Deleting does not erase the item right away: it goes to the base’s Trash tab, next to Items, and stays there for seven days. The item leaves agent answers immediately, because SquadOS deletes its vectors; the record and the source file are kept during that period. An item that is Processing cannot be deleted: wait for processing to finish.

In the Trash tab, each item shows its type and the date it will be permanently deleted. Restore returns the item to Items as Pending: it is indexed again and comes back to agent answers once it reaches Processed. People with bases.delete can restore and, under the departments model, so can people who were given Edit on that base. Having only Delete on the base lets someone send the item to Trash, but not restore it. Without permission to restore, the tab lists the items without the button.

When the period ends, SquadOS permanently deletes the record and the source file, and the item can no longer be restored. There is no button to delete it before then. Delete base, in the header’s three-dot menu, is different: it removes the base and all of its items, including those in Trash, and cannot be undone.

Export CSV

Export CSV opens Export the base as CSV and requires only bases.view. Click Download CSV: SquadOS builds the file on the server and the download starts on its own. If the browser does not start it, use Download the file.

The file contains every active item in the base, including items that came from a file or a crawl. Each item carries the text that indexing uses: the optimized version, when there is one; otherwise, the item’s saved text or the text extracted from its source file. For a PDF, it is the text that indexing extracted from the document. Original documents are not included in the CSV; to keep them, store a copy outside SquadOS.

The file name is the base name in lowercase, without accents and with hyphens, for example return-policies.csv. It uses a semicolon (;) as the separator, UTF-8 with a BOM so Excel opens accented characters correctly, and the columns id;title;content.

The CSV is either complete or not produced at all. If any item is pending or processing, ended with Error, or has no text that can go into the file, no file is generated: the dialog lists those items, each with the reason and the fix. Above 50 items, use Download the full report. Resolve the listed items and export again.

After editing the file, upload it through Import CSV with the Sync base option (requires bases.write and bases.delete) to make the base match it; text items missing from the file go to the Trash tab and stay there for seven days, while File and Crawl items stay as they are. Keep the id column as it came out: it links each row to an item in the base, and a row without an id becomes a new item.

Values that begin with =, +, -, @, a tab, or a carriage return are written with a leading apostrophe so the spreadsheet does not run them as formulas. When syncing, SquadOS removes that apostrophe from rows with an id, and the content comes back exactly as it was.

Keep the base trustworthy

Use one base per domain and avoid mixing unrelated policies.
Give items specific names: the name accompanies every chunk and also influences retrieval.
Use headings and keep conditions, exceptions, and effective dates with the main rule.
Remove revoked versions and duplicates to avoid conflicting answers.
After editing, optimizing, moving, or deleting, wait for Processed and test real questions with the connected agent.
Check AutoLearn to turn recurring gaps into reviewed items. See Learning Opportunities.