> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flexxible.com/llms.txt
> Use this file to discover all available pages before exploring further.

# What to write in the knowledge base

> What knowledge is useful for people and agents, what's best left out and how to write pages that are easy to find and apply.

A knowledge base is useful when it contains what can't be known any other way. This page summarizes what's worth documenting, what's best left out and how agents interpret what you write.

## What to document

Document what an AI model, or a newcomer, can't know about your organization:

| Type of knowledge | Examples |
| - | - |
| How the environment is set up | Which VPN client is used and where it's installed from, which Wi-Fi networks exist, what the license groups are called. |
| Local rules | "Never delete the OST for shared mailboxes", "ask before touching an executive's laptop". |
| Owners and escalation | Who is responsible for each system, who to escalate to and during what hours. |
| Known quirks | An office printer that only works with a specific driver, an application that needs special permissions. |
| Fixes specific to your organization | The fix for your VPN client, your proxy or your GPOs. |

## What to leave out

* **Generic troubleshooting.** Any model already knows how to flush the DNS cache or what an error code generally means. Pages that repeat it make it harder to find what's actually specific to your organization.
* **What's happening right now.** An ongoing incident, such as "since the October update Outlook hangs on eleven laptops in Madrid", isn't a page: it goes out of date within hours. Agents get the current state of devices from the platform's live data.
* **Passwords, keys and other secrets.** Store them in the [Vault](https://docs.flexxible.com/en/features/flexxible-kb/vault.md) and link to them from the page.

> [!WARNING]
>
> Don't write passwords or keys in a page's text. The editor warns you when what you paste looks like a secret and offers to store it in the Vault.

## How agents interpret a page

Flexxible Assist agents read the knowledge base as a set of facts and rules, not as a script to run blindly:

* **Rules are binding.** If a page says something must not be done, the agent respects it even if its own diagnosis points in another direction.
* **Fixes are hints.** The agent checks them against what it observes on the device. If the fix doesn't match what it sees, it follows what it sees and reports that the page wasn't correct.
* **What's missing is reported.** When the knowledge base doesn't have what they needed, or has it wrong, agents report it in [Missing from the KB](https://docs.flexxible.com/en/features/flexxible-kb/gaps.md). They don't create or rewrite pages on their own.

That's why it's worth distinguishing in the text what's a rule ("never", "always", "before…") from what's a procedure that worked.

## How to write a useful page

| Practice | Why it helps |
| - | - |
| One topic per page | Search returns the page and section that answer. A page that mixes topics answers all of them worse. |
| Descriptive titles and headings | People and agents go straight to the section they need. |
| Symptoms as a user would describe them | Makes it easier to match the page with the real incident, in other languages too. |
| Exact names and versions | "GlobalProtect 6.3.1 from Company Portal" can be checked; "the VPN client" can't. |
| Numbered steps and expected result | Lets you check whether the procedure worked. |
| When to escalate and to whom | Shows at what point a person needs to step in. |
| Pages inside pages | An office with its printers inside, or a system with its procedures, makes it clear what each page applies to. |

Below the title, each page shows a one- or two-sentence summary, **In short**, which Teammate writes from the content and updates after each change. People and agents also get it in search results. If the summary doesn't reflect what's important, improve the page: the summary corrects itself.

## Keep the knowledge base up to date

* **Fix it on the spot.** When a procedure changes, edit the page or tell [Teammate](https://docs.flexxible.com/en/features/flexxible-kb/teammate.md): "The VPN client is now GlobalProtect 6.4.0".
* **Review Missing from the KB.** It gathers what agents needed and didn't find, sorted by weight.
* **Check each page's usage.** Each page shows how much people and agents have used it in the last 30 days and how many of the sessions that used it were resolved without escalating. See [Page usage](https://docs.flexxible.com/en/features/flexxible-kb/pages.md#uso-de-una-página).
* **Delete what no longer applies.** An outdated page alongside a newer one produces contradictory instructions. A deleted page can be restored.

If your organization needs a record of which version of a page has been checked, it can turn on [page validation](https://docs.flexxible.com/en/features/flexxible-kb/validation.md). To find out which pages aren't helping their readers, it can turn on [ratings](https://docs.flexxible.com/en/features/flexxible-kb/ratings-reactions.md).

## Next steps

* [Write and edit pages](https://docs.flexxible.com/en/features/flexxible-kb/editor.md)
* [Missing from the KB](https://docs.flexxible.com/en/features/flexxible-kb/gaps.md)
* [Flexxible Assist agents](https://docs.flexxible.com/en/features/flexxible-kb/assist-agents.md)
