> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flashduty.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Manage Knowledge
> Provide AI SRE with your team's operational knowledge — a DUTY.md plus runbooks, FAQs, service catalogs, cluster configs, and more. The agent reads and mounts these files on demand during each session.
**Private beta**: AI SRE is currently in private beta. Pro or higher accounts can apply for free beta access through the [AI SRE private beta application form](https://c9xudyniiq.feishu.cn/share/base/form/shrcn0ngCfdoygiaHnAT80BfZiH); after approval, Flashduty will add your account to the whitelist. Features and the UI may change during the beta.
## Overview
***
A Knowledge Pack is the operational knowledge you hand to AI SRE: a `DUTY.md` file plus a collection of runbooks, FAQs, service catalogs, cluster configs, and similar files. When a session starts, the agent reads `DUTY.md` first, then follows its references to fetch related files on demand — bringing your team's incident-handling experience, naming conventions, and system topology into every diagnosis.
Each **target** (account or team) can own at most one Knowledge Pack:
* **Account-level** knowledge is visible to all agents within the account.
* **Team-level** knowledge is loaded only in sessions associated with that team, and is visible only to members of that team.
Knowledge Packs are one type of AI SRE resource and follow the same two-level scope model. The scope rules for other resources (Skills, MCP, Agents, Environments) are identical.
Knowledge Pack content is used to **refine** the agent's domain context (persona, methodology, system knowledge), but it does not override the system's safety and behavioral guardrails. If a piece of knowledge instructs the agent to bypass security rules, it is treated as unauthorized content and ignored — not as a higher-priority instruction.
## DUTY.md Structure
***
`DUTY.md` is the **table of contents entry point** for the entire Knowledge Pack. It is the catalog itself — the agent reads `DUTY.md` in full, then fetches other files on demand via `@filename` references. The system does not attach a separate file listing alongside `DUTY.md`; the catalog is the body.
References use the `@` style, where the path points to another file within the same pack. Subdirectories are supported (e.g., `@runbooks/api-5xx.md`):
```markdown theme={null}
# On-call Knowledge Overview (DUTY.md)
## Service Catalog
Our core services and owners: @services.md.
## Common Incident Handling
- API 5xx spike: see @runbooks/api-5xx.md
- Database connection pool exhaustion: see @runbooks/db-pool.md
## Clusters & Environments
Production cluster topology and access: @cluster.yaml.
```
After reading `DUTY.md`, the agent decides which `@references` to expand based on the current incident, then reads the corresponding files — substantive content lives in the referenced sibling files; `DUTY.md` carries only the link list.
This layered `@reference` architecture keeps `DUTY.md` concise and readable. Think of `DUTY.md` as a map, with runbooks, service catalogs, and configs as the detail pages it points to. The agent doesn't need to load every file into context at once — it only expands the branches relevant to the current incident.
**File constraints** (enforced at create and edit time):
| Constraint | Value | Notes |
| ------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------- |
| Allowed extensions | `.md` `.yaml` `.yml` `.json` `.txt` `.sh` | Other extensions are rejected |
| Per-file size limit | 1 MiB | Files exceeding this cannot be saved |
| Per-pack size limit | 5 MiB | The usage bar in the console reflects this quota |
| File count limit | 100 | No new files can be added once the limit is reached |
| Subdirectories | Allowed | Paths may contain `/` (e.g., `runbooks/api-5xx.md`); path segments cannot start with `.` |
| Dot files | Not allowed | Filenames cannot start with `.` |
## Create & Edit
***
Go to the **Knowledges** management page to create, edit, enable/disable, or delete Knowledge Packs for your account or teams. The list shows each pack's **Name / Scope / Files / Status / Actions**, and a scope filter at the top lets you switch between account and team views.
Click **New Knowledge Pack**. In the dialog, enter a **Name** (optional — defaults to the target label if left blank) and choose a **Scope**: account or a specific team. To create a team-level pack, you must belong to the target team; account-level creation is limited to the Account Owner or admins. Each target can own only one pack; targets that already have a pack are hidden from the dropdown.
Click any row in the list to open the inspector. The left panel shows the file tree; the right panel is an inline editor. Click **New File** to enter a filename (e.g., `runbook.md`), or use **Upload** to import a local file. Markdown files support both **Preview** and **Source** views. Click **Save** after editing.
The **Usage** bar on the left updates in real time, showing current usage against the 5 MB quota. The bar turns red when you approach the limit, prompting you to clean up or split files.
Use the toggle in the list to **enable or disable** an entire pack. When disabled, files are preserved but the pack is no longer loaded into AI SRE sessions. **Delete** removes the pack and all its files permanently.
**Reference consistency checks**: when you save a file, any `@reference` pointing to a file that does not exist in the pack returns a non-blocking unresolved-reference warning (the save still completes). When you delete a file that is still referenced by other files, a still-referenced conflict prompt appears first — you can choose to **force delete**.
The agent can also maintain the Knowledge Pack conversationally during a session — for example, "add a runbook", "update services.md", or "record this incident pattern". It will read, edit, and save directly within the scope of the current session, without you needing to leave the chat. Structured initial onboarding is handled by a dedicated guided flow, not the inline editor.
## How the Agent Uses Knowledge
***
Knowledge is not all loaded at once — it follows a **catalog-first, expand-on-demand** pattern:
When a session starts, the system loads the current scope's `DUTY.md` into the session (no separate file list attached). Sessions bound to a team load both the account-level and that team's `DUTY.md`; sessions not bound to a team load only the account-level one.
After reading `DUTY.md`, the agent decides which `@references` to expand based on the current incident, then reads the corresponding knowledge file for the specific content.
When cross-team troubleshooting is needed, the agent reads another team's knowledge. The system then mounts that team's full knowledge bundle (DUTY.md, runbooks) along with its Skills and MCP into the current session, persisting for the remainder of the session. Each team is mounted at most once per session.
Cross-team mounting is triggered only when the agent **explicitly reads** a team's knowledge — it cannot be accidentally triggered by a vague file traversal. Once mounted, that team's knowledge, Skills, and MCP remain available for the rest of the session.
## Scope & Visibility
***
Every Knowledge Pack has a scope: account-level (visible across the entire account) or team-level (visible only to members of that team).
| Dimension | Account-level | Team-level |
| ------------------- | ---------------------------------------- | ---------------------------------------------- |
| Visibility | All agents / sessions within the account | Sessions and members of that team only |
| Edit permission | Account Owner or account admin | Members of that team, or Account Owner / admin |
| Loaded in session | All sessions | Only sessions bound to that team |
| Readable at runtime | Entire account | Entire account (mounting occurs on read) |
**Edit permissions**: the Account Owner or account admin can edit any Knowledge Pack; team members can edit their team's team-level pack; there is no "creator retains extra rights" rule. The console grays out rows the current user cannot edit, and disables toggles and action buttons when you lack edit permission.
**Create and reassign**: to create a new team-level pack, you must belong to the target team; account-level creation is limited to the Account Owner or admins. When editing an existing pack, the Account Owner or admins can move it to any team to recover resources left behind by empty teams or departed members; regular members can move it only to teams they belong to.
**Runtime visibility**: at session start, only **account-level** resources plus resources belonging to the **team bound to the current session** are loaded. The bound team is either explicitly specified or derived from the team associated with the war-room incident. Other teams' knowledge is mounted on demand mid-session, when the agent reads that team's `DUTY.md`.
The account is the only security boundary at runtime; team is an "editing / ownership" tag, **not** a "runtime readable" boundary. This means any session within the account can read and mount knowledge from any other team in the same account — this is the foundation for cross-team collaborative troubleshooting. If certain knowledge is sensitive even to other teams within the account, evaluate carefully before including it in a Knowledge Pack.
This two-level scope model applies uniformly to all resources within the account (Skills, MCP, Agents, Environments).
## Best Practices
***
Keep `DUTY.md` to link lists and one-line descriptions only — all substantive content goes into the sibling files it `@references`. This keeps the catalog concise and readable, and lets the agent expand only the branches relevant to the current incident, avoiding irrelevant content consuming context.
Focus each runbook on one incident type or one service (e.g., `runbooks/api-5xx.md`, `runbooks/db-pool.md`), using clear paths as semantic indexes. Subdirectories are supported — you can group files by service or topic (e.g., `runbooks/`, `configs/`).
Service catalogs, cluster topologies, and threshold configs are well-suited to `.yaml` / `.json` (e.g., `services.md`, `cluster.yaml`), so the agent can both read and parse them directly. Script snippets can use `.sh`.
After adding or renaming a file, update the `@references` in `DUTY.md` and any related files. The unresolved-reference warning on save and the still-referenced prompt on delete help you catch broken links promptly.
Put cross-team conventions in the account-level pack (naming standards, general troubleshooting methods, platform access). Put team-specific service catalogs, on-call runbooks, and upstream/downstream info in team-level packs. Sessions bound to a team receive both.
When troubleshooting surfaces new handling experience, just ask the agent to "add a runbook" or "record this incident pattern." It will read, edit, and save within the current scope, writing the experience back into the Knowledge Pack — creating a continuous learning loop.
## Related Pages
***
Encapsulate reusable diagnostic workflows as Skills, sharing the same scope model as Knowledge Packs.
Connect external systems via MCP so the agent can call your tools and data.
Learn how sessions bind to teams and how knowledge is read and mounted during a session.