Knowledge Base

This guide covers writing, versioning, publishing and sharing knowledge articles, how a client organization controls what its provider shares with it, and how articles reach readers through the Help Center, semantic search, the Sol assistant and ticket deflection.

Audience: MSP technicians and administrators, organization administrators, and anyone supporting them.

---

What it is

The knowledge base stores articles, procedures, runbooks, FAQs, policies, templates and guides as Markdown, each with a status, a category and a visibility setting. Every content change is versioned and restorable. Published articles are readable by the audience their visibility names and are indexed for semantic search, so they can be surfaced by the Help Center, the Sol assistant, and the self-help panel shown to a customer while they are filing a ticket.

It is one corpus with two front doors — an authoring surface for staff, a read-only Help Center for customers — and a control surface in between, where a client organization decides how its provider’s articles appear to its own readers.

---

Concepts

Articles live in knowledge_documents, their history in knowledge_revisions, categories in knowledge_categories, client-side decisions in knowledge_share_overrides, and feedback in knowledge_feedback. Deleting an article deletes its revisions, overrides and feedback with it.

---

Roles and permissions

The role hierarchy is platform administrator > MSP administrator > MSP technician > organization administrator > power user > CUSTOMER`.

Authoring is floored at organization administrator. Power users and customers are deliberately excluded because the authoring routes return drafts and articles in review; those readers use the portal routes, which only ever return published articles.

Client-sharing controls (choosing which clients receive an article) appear on the MSP portal only, because the client list they operate on is an MSP concept. The receiving side of that relationship — deciding what to do with an article someone shared with you — is available to any organization.

---

Walkthrough — writing and publishing an article

1. Go to Knowledge Base → New Article (/msp/knowledge/new or /org/knowledge/new).
2. Enter a title (up to 200 characters) and write the body in the Markdown editor. The toolbar inserts headings, bold, italic, lists, links, inline code, code blocks, quotes and rules; Preview renders the result and the expand control gives you the full screen.
3. Pick a category from your organization’s list. Required to publish, optional to save as a draft. If the list is empty or missing what you need, see section 10.
4. Pick a type.
5. Pick a visibility — see section 9.
6. Add tags. The MSP portal takes them one at a time via Add; the org portal takes a comma-separated list. Either way, anything left in the box when you submit is included.
7. Choose one:
   • Save as Draft — stored, readable only by authors, not indexed.
   • Publish Article — readable immediately by the audience you chose, and indexed for semantic search.

Editing an article

1. Open the article and choose the Edit tab.
2. Change the title, body, category, tags or (org portal) visibility.
3. Optionally add a change note — a sentence recorded against the version this edit replaces, so history reads as a story rather than a list of dates.
4. Save Changes.

Changing the title or body increases the version, snapshots the previous text into history, and re-indexes the article. Changing only tags, category, status or visibility leaves the version alone — what a reader reads has not changed.

---

Walkthrough — sharing an article with clients

MSP portal only. One article, written once, published to the clients who should have it.

1. Open the article on the MSP portal and choose the Sharing & Access tab.
2. Choose a visibility:
   • MSP Internal Only — your technicians. No client ever sees it.
   • All Clients — every organization your account manages.
   • Selected Clients — only the organizations you tick.
   • Platform-wide — every tenant. Platform administrators only; any other author is scoped to their own account (see section 9).
3. If you chose Selected Clients, tick the client organizations in the Client Access panel.
4. Choose Update Visibility.

What happens next is the client’s decision. By default your article appears in their Help Center immediately; a client that has turned on hold-for-review sees it as pending until an administrator there publishes it, and any client can hide it or re-file it under one of their own categories. None of that changes your copy.

Sending someone the link

Share Link on the article header copies the current URL. It is a staff URL — a customer following it will not have access. Customers reach the same article at /user/help/<id>.

---

Walkthrough — controlling what your provider shares with you

Any organization, at Knowledge Base → Shared With Us (/org/knowledge/shared or /msp/knowledge/shared).

Sharing is your provider’s decision; how it appears to your people is yours.

1. Open Shared With Us. Every article another tenant has published to your organization is listed with its current state.
2. Choose how new shares behave:
   • Publish automatically (the default) — anything your provider shares appears in your Help Center right away.
   • Hold for review — nothing new reaches your readers until you publish it here. Use the toggle at the top of the page.
3. For any individual article:
   • Publish — show it in your Help Center.
   • Hide — suppress it. It stays available to you here, and your provider’s copy is untouched.
   • File under — re-file it into one of your categories, so it sits in the tile your readers expect rather than the one your provider used.

A pending article is counted in a banner at the top of the page, so a hold-for-review organization can see at a glance that something is waiting.

---

The article lifecycle

DRAFT ──────────► IN_REVIEW ──────────► PUBLISHED ──────────► ARCHIVED
  ▲                   │                     ▲                     │
  └───────────────────┘                     └─────────────────────┘
        Return to Draft                    Restore to Draft
  │                                         ▲
  └─────────────── Publish ─────────────────┘

Every transition is a button on the article header.

Archive, do not delete, when you want an article off the Help Center. Archiving is reversible and keeps the article, its history and its feedback. Delete is permanent and takes all of that with it; the article header asks you to confirm and says so.

There is no approval gate on In Review — anyone who can edit can also publish. Treat it as a shared to-do marker, not an authorization step.

---

Version history

Open an article and choose the History tab. The tab label carries the number of earlier versions.

• The list shows the current version at the top, then every superseded version, newest first, with its change note and date.
• Select a version to read it in full, rendered.
• Restore version N rolls the article back.

Restoring keeps history rather than rewriting it: the current text is snapshotted first and the version number moves forward. Restoring version 1 of a two-version article produces version 3, and version 2 is still there — so a restore can itself be undone.

A restored article is re-indexed if it is published.

Metadata-only edits do not create a version. Only the title and body do.

---

Visibility in detail

Visibility is evaluated on every customer-facing read. A customer sees an article only if one of these is true:

Four properties worth knowing:

• “Platform-wide” is not a way to reach other tenants. If an author who is not a platform administrator asks for it, the article is stored as Account instead. An edit cannot re-acquire it either.
• MSP Internal is absent from the customer rule set entirely, rather than being filtered out afterwards. It cannot leak through a new read path that forgets to exclude it.
• A share is not a publication. The receiving organization’s own state for a shared article is part of the same rule, so hiding one removes it from that client’s Help Center, semantic search, related articles, Sol and deflection at once.
• Staff see everything within their own tenant, plus the global corpus, regardless of visibility level. Visibility governs customer reads; tenant scoping governs everyone.
• Ticket knowledge suggestions are the one staff read that also applies a client’s share decisions. Because the panel exists to find an article to send to a requester, it evaluates the ticket organization’s rules as well as the caller’s own — which is what lets an MSP-shared article be suggested at all, and what keeps a hidden one out of the client’s own staff view.

---

Categories

Categories are records your organization owns, at Knowledge Base → Categories (/org/knowledge/categories or /msp/knowledge/categories).

The same list drives the authoring picker, the article-list filter and the customer Help Center tiles, so an article files itself into a tile a reader can actually click.

A default set is created the first time you open the knowledge base: Getting Started, How-To Guides, Troubleshooting, Account & Access, Billing & Invoices, Policies, Technical Reference, Announcements.

On the Categories page you can:

• Add a category with an optional description.
• Rename one. Every article currently filed under the old name is re-filed automatically, as is every client-side override pointing at it.
• Remove one. Articles filed under it keep their category text and appear under Other until they are re-filed. No article is ever deleted with a category.

Duplicate names are rejected with a clear message rather than a server error.

The Help Center shows a tile for every category that has at least one article the reader can see, plus a tile for any category name in use that has no record — so nothing becomes unbrowsable — plus Other for articles with no category at all.

---

How customers find articles

The Help Center is at /user/help. It offers:

• A search box that runs both a keyword search and a semantic search.
• Category tiles with a live article count, drawn from your organization’s categories.
• Four featured articles — the four most recently updated.

An article page (/user/help/<id>) shows the rendered Markdown, an estimated read time, up to three related articles from the same category, and a “Was this helpful?” widget.

Read time is calculated at 200 words per minute, rounded up, with a floor of one minute. Opening an article increments its view counter.

Customers landing on the older /user/knowledge paths are redirected here.

---

Search, indexing and AI credits

Two search mechanisms run together.

Keyword search matches substrings in the title and body (and, on the portal route, tags). It is case-insensitive and needs no configuration.

It finds articles that answer the question without sharing its wording.

The Help Center search box runs both and lists semantic hits the keyword pass did not already return under Related to what you described, with a match percentage. Ticket deflection, the Sol assistant and the mobile Help Center use semantic search directly.

When indexing happens

An article is indexed when it enters Published — on creation if you publish directly, on the transition if you publish a draft — and re-indexed when a published article’s title or body changes, or when a version is restored.

AI credits

Indexing costs one AI credit per article; authoring costs nothing.

Only indexing is charged. This is deliberate — a ticket page must not fail to load because an account is out of AI credits.

Writing, editing, publishing, versioning and restoring are core knowledge-base actions and are never refused.

It is marked not indexed, the editor tells you why, and the article list shows a banner offering to re-index. Keyword search and browsing find it in the meantime; semantic search, Sol and deflection do not.

Credits are charged only for work that was attempted. A draft is never indexed, so saving drafts costs nothing.

Re-indexing

When any of your published articles are unindexed, the article list shows a banner with a Re-index now button. It processes up to 100 articles per run, reports how many were indexed and how many remain, and stops early with a clear message if the account runs out of credits mid-run rather than reporting a misleading pile of failures.

---

Linking articles to assets

An article can be linked to the configuration items it documents. The link is what turns a runbook into part of the CMDB: without it, the article that explains how to fail over a specific firewall is findable only by remembering its title.

From the article. Open it and use the Assets tab. Pick the asset, say how the article relates to it, and link it:

From the asset. Open the asset and use its Knowledge tab. The same link can be made from either side, because the moment you want it is usually the moment you are looking at the device.

Who can link what

An asset can be linked when it is within your own reach — your account’s organizations, widened for MSP staff to the clients you service. That is deliberately your reach and not the article’s owning organization, because the case that matters is exactly where the two differ: an MSP runbook lives in the MSP’s own organization and documents a client’s firewall.

Linking never widens who can read

The link does not grant anyone access. Which articles a reader sees is still decided by the article’s visibility, evaluated fresh on every read. So an MSP-internal runbook linked to a client’s server appears on the MSP’s view of that server and does not appear on the client’s — the same asset page, different articles, because they are different readers.

Drafts follow the same rule with one addition: you see your own organization’s drafts on an asset page (so “the runbook for this box is still being written” is visible and true), and a customer never does.

Where the links show up

• The asset’s Knowledge tab, in the organization and MSP portals.
• Ticket suggestions. A ticket that names an asset gets that asset’s articles suggested alongside the semantic matches, marked as linked rather than guessed. This works even when the semantic half returns nothing — an unindexed corpus, or a runbook whose wording shares nothing with how the problem was reported (“SW-CORE-01 failover” versus “internet keeps dropping in the warehouse”).

Deleting an asset removes its links and leaves every article intact.

---

Ticket deflection

When a customer describes a problem on /user/requests/new, Solidlio searches the knowledge base and offers matching articles before the ticket is submitted.

• The search runs once the description passes 30 characters, debounced by 1.5 seconds, and re-runs as the text changes.
• Up to five articles are offered, each above 0.6 relevance.
• “This solved my issue” cancels ticket creation.
• This panel does not carry over once the ticket exists. An open ticket shows a different panel, driven by the ticket itself rather than the description that was typed here — see Suggestions on an open ticket below.

Deflection applies the full visibility rule set, so a customer is offered exactly the articles they are allowed to read — including the ones their provider shared with them and their own organization has published, and never an MSP-internal one or one their organization has hidden.

Suggestions on an open ticket

Deflection runs before a ticket exists. Once it does, the Knowledge Suggestions panel searches on the ticket’s own subject and description and offers up to five articles, each with a match percentage.

It appears on all three portals, and what it offers is tiered:

Each tier is a superset of the one above it, so a suggestion can never reach someone who would not be allowed to open the article.

The MSP row describes a ticket belonging to a managed client. On a ticket raised inside the MSP’s own organization there is no client tenant to add, so MSP staff see exactly the Organization staff set — their own articles at every visibility level, MSP-internal runbooks included.

Staff rows carry an Insert link action that appends a link to the reply being drafted — it never replaces what has already been typed. An article the requester cannot open is marked Internal only, and its link points at the staff knowledge base rather than the Help Center, so pasting one into a reply cannot expose it.

An end user sees the panel only when there is something to show. Nothing appears while the search runs, or if it finds nothing, or if it fails.

Only published, indexed articles can be suggested.

---

The Sol assistant

Sol can read the knowledge base on all four portals, through two tools:

• Search Knowledge Base — keyword search over titles, bodies and tags of published articles, returning up to 20, each truncated to 300 characters. Accepts optional type and category filters.
• Get Knowledge Article — the full body of one article by id.

Both apply the visibility rule set against the caller’s portal, tenant and share decisions, so Sol answers a customer only from articles that customer could have opened themselves.

Separately, when Sol answers a question in a knowledge context it grounds the reply in up to five retrieved articles and reports whether that grounding succeeded — a retrieval outage is reported as an outage rather than presented as “nothing relevant found”.

---

Feedback and analytics

Every “Was this helpful?” submission writes a feedback row and an audit-log entry recording the article title, the verdict, any comment, and who submitted it.

The article’s Analytics tab shows:

Vote counts and the helpfulness bar are shown on the MSP portal; the org portal shows views.

Comments left with feedback are stored and readable in the audit log, but are not surfaced in the Analytics tab.

---

Mobile

The mobile app carries a customer Help Center (browse, categories, semantic search, article detail with related articles) and a read-only MSP article browser. Authoring, versioning, publishing, sharing, category management and analytics are web-only.

---

Plan tiers

The knowledge base carries no plan gate. Writing, versioning, publishing, sharing, categories, the Help Center, feedback and analytics are available on every tier, including Free.

Semantic indexing consumes AI credits (one per article indexed), so how much of your corpus is searchable at once is bounded by your plan’s AI credit allowance rather than by a feature flag. Sol conversations are metered per turn; searching the knowledge base inside one is part of that turn. Semantic queries are not separately charged.

---

Troubleshooting

403 FORBIDDEN — Insufficient role when opening the Knowledge Base. The account is a power user or a customer. Authoring needs organization administrator or above. Customers use /user/help.

404 NOT_FOUND — Knowledge document not found for an article that exists. It belongs to another tenant. Cross-tenant reads return “not found” rather than “forbidden” so identifiers cannot be probed. The same response covers a genuinely missing id.

404 NOT_FOUND — Shared article not found when changing a shared article. That article is not shared with your organization. The same response covers an article that does not exist, so ids cannot be probed.

400 BAD_REQUEST — "X" is not one of your categories. A category override must name a category your organization has defined. Add it on the Categories page first.

409 CONFLICT — A category named "X" already exists. Category names are unique within an organization.

“Saved, but not added to semantic search.” Expected, and the article is safe. Use Re-index now on the article list once the cause is resolved.

A published article does not appear in semantic search or deflection. Check the article header for a Not indexed marker and the list for the re-index banner. Editing the title or body also re-indexes it.

An article your provider shared is not in your Help Center. Check Shared With Us. It is either hidden, or your organization holds new shares for review and this one has not been published yet.

An article set to “Platform-wide” saved as “All Organizations”. Expected. Only a platform administrator can publish across tenants; every other author is scoped to their own account.

400 BAD_REQUEST — Search query is required. The semantic search route was called without q.

400 VALIDATION_ERROR — Request validation failed. Check the response details. Most often a title over 200 characters, an empty body, or a type outside the accepted seven.

---

Limits and known behaviour

• In Review is not an approval gate. Anyone who can edit can publish. It records intent, not authorization.
• Type cannot be changed after creation. Title, body, category, tags, status and visibility can all be edited.
• Category is stored as text on the article. Renaming a category re-files articles automatically, but an article filed under a name with no category record (an older one, or one from another tenant’s taxonomy) shows in the Help Center under its own tile rather than a managed one.
• List category and visibility filters are page-local. Search and status are applied by the server; the category and visibility dropdowns narrow only the articles on the page you are looking at.
• Re-index processes up to 100 articles per run. The response reports how many remain, so a large backlog takes several runs.
• Feedback comments are not shown in Analytics. They are stored and appear in the audit log.
• Views are a running counter, not a series. There is no per-day view history, so no trend can be shown.
• No anonymous access. Every knowledge route requires an authenticated session; there is no public article URL.
• Authoring is web-only. Mobile is read-only.
• Ticket suggestions are not queue-aware. They scope the ticket by account, not by queue access, so a staff member who cannot see a restricted-queue ticket in the ticket list could still request suggestions for it by id. The articles returned are only ones that person may already read, so nothing leaks from the knowledge base; what it reveals is that the ticket exists.