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.

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. The same rules apply to Delete in an individual row menu.

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.

Deletion has no undo. The record leaves the base immediately, while vector, chunk, and source-file cleanup proceeds through an asynchronous queue. Keep the original source outside SquadOS before confirming an important deletion.

Export CSV

Export CSV creates <base-name>-items-YYYY-MM-DD.csv with title;content columns. The confirmation reports how many records will be exported and how many will be skipped.

The file includes only items whose content field is populated. It may omit documents whose text exists only in private chunks, and it exports the record’s original content rather than necessarily the optimized revision shown under View. Treat the CSV as a partial export for text inspection or migration, not as a complete base backup.

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.