Sensei Knowledge Base

Move an article (by UUID or slug) to ARCHIVED status — hides it from default reader views but preserves history. published_at is preserved. Idempotent. Requires kb:write.

Create a new article from Markdown. Body is converted to TipTap-compatible HTML server-side; raw HTML in the input is escaped (no <script>, <iframe>, etc). Defaults: status=DRAFT, no category; department-scoped users default to their assigned departments, while admins/service tokens default to no restriction. Pass status="PUBLISHED" to publish immediately. category_slug = the CONTENT rubric (a topic folder, see kb_list_categories). department_ids = the ACCESS AUDIENCE — which departments may see it (see kb_list_departments). These are different: if the user says "put this in <name>" and <name> is a department, pass its id in department_ids — do NOT create a category named after a department. Requires scope kb:write.

Create a new KB section (CATEGORY = a content rubric / topic folder). The slug is derived from the name (transliterated) and de-duplicated within the org. Pass parent_slug to nest it under another section — a nested section inherits its parent's department. position defaults to the end of the sibling list. NOTE: a category is NOT a department. A DEPARTMENT is an access audience (kb_list_departments); to restrict an article to a department, pass its id in department_ids on the article — do not create a category named after it. If the requested name matches an existing department, this tool refuses unless confirm=true. Requires scope kb:write.

Delete a KB section (by UUID or slug). Articles in it are NOT deleted — their category link is cleared (they become uncategorised). Direct child sections are re-parented to root. Irreversible. Requires scope kb:write.

Fetch a single article by UUID or slug. Returns the full HTML content (TipTap-compatible) plus metadata. Set include_content=false to skip the body when only the summary is needed.

Return related articles for a given article (by UUID or slug). Returns the union of manual cross-links and embedding-nearest neighbours, capped at ``limit``. Manual links come first.

List articles ordered by recency. Supports filtering by category slug and status. Pagination via offset/limit.

Return the full category tree as a flat list. Each item carries ``parent_slug`` so clients can rebuild hierarchy. Ordered by (parent, position).

List the organization's departments (access audiences). A DEPARTMENT controls WHO can see an article — it is NOT a content rubric (that is a category, see kb_list_categories). Returns id, name, type (BRANCH/DEPARTMENT) and parent. To restrict an article to one or more departments, pass their ids in ``department_ids`` on kb_create_article / kb_update_article. Call this to look up a department's id by name before assigning it.

Move an article (by UUID or slug) to PUBLISHED status. Stamps published_at when transitioning from draft. Idempotent — already-published articles return unchanged. Requires kb:write.