¶Knowledge base

A tree of articles, one per workspace. Knowledge, in the sidebar.

¶The shape

A tree on the left, a document in the middle, its headings on the right.

Nesting is arbitrary, up to six levels — unlike an epic, which is one level deliberately. A plan with grandchildren stops being readable; documentation is the opposite, because the nesting is the organisation. Six is deeper than any documentation that is working.

Only open branches are drawn. A collapsed section costs nothing, which is what keeps a base of several hundred pages usable.

Following a link to a page four levels down opens the branches above it. Otherwise you would see the article and not where it sits, which is most of what a tree is for.

¶Drafts

A new article starts unpublished and appears under Drafts at the top of the tree, visible only to whoever is writing it.

Not really a permission — a courtesy. Half a page is worse than no page, and somebody who finds one through search will act on it.

¶Where the documents live

On disk, in storage/knowledgebase, one HTML file per article. The database row is metadata: title, parent, position.

Three things follow from that, and all three are why:

A tree of four hundred articles is drawn on every page load and none of it needs the prose. In a column, every sidebar render would drag megabytes of text through the database to list some titles.

The documents are legible without us. Somebody with shell access can grep them, back them up with rsync, or read one without a database client — which is worth something for the page a team writes about how to restore the database.

And a filesystem is not transactional, so the code is written not to need one: writes go through a temporary file and a rename, so a reader arriving mid-write gets the old document rather than half of the new one. A missing file reads as empty rather than throwing — a restored database should render a page somebody can fix, not a 500.

Point FELAGI_KNOWLEDGEBASE_PATH at a shared volume if more than one machine serves the application.

¶Search, given that

search_text on the row is a plain-text copy of the file, rebuilt on every save. A cache, not the truth — the same relationship issues.spent_minutes has to time_entries. SQL cannot grep a filesystem, and reading four hundred documents per keystroke is not a search feature.

¶Writing

flux:editor, like everything else in Félagi that is prose.

HTML is sanitised on the way in through the same allowlist as comments and issue descriptions. That matters more here than anywhere: the file will outlive this code and be read by things that are not this application.

Tables survive. No toolbar in Flux can produce one, so they arrive by paste — out of a wiki, a spreadsheet, or the tool a team is migrating from — and the most useful page in a knowledge base is usually a table of hostnames and addresses.

¶Contents

The list on the right is derived from the document every time it is drawn, and the anchors in the article are written by the same function. A contents list that can disagree with the article is worse than none, and the only way it cannot disagree is if neither is stored.

¶Attachments

Diagrams, exports, PDFs — up to ten at a time, 25 MB each, through the same machinery as attachments on an issue. Served by the application rather than from a public folder, so every request checks that you are in the workspace the file belongs to.

¶Who may write

Anybody who works here. Deliberately the widest gate in the product: a knowledge base only admins may write to is a knowledge base nobody writes to, and the failure mode of documentation is always that it was never written rather than that the wrong person wrote it.

Deleting is narrower — the author or a workspace admin — because a section takes its children with it. A colleague can correct your page; removing it and everything filed under it is a different act.

¶Not there yet

• No drag to reorder. Position is a number and a new article goes last; moving one means picking a different parent.
• No version history. The file is overwritten. There is no diff and no way back to yesterday's wording.
• No comments on an article, and no way to suggest an edit.
• No links between articles beyond ordinary hyperlinks — nothing knows what points at what, so nothing warns you before a delete.
• No linking an article to an issue, in either direction.
• Not in the API, and not in the import.
• Search is LIKE. No ranking, no fuzzy matching, no highlighting of the matched phrase. Fine at the sizes this is built for.
• Nothing an agent reads. Skills are what an agent is given; a knowledge base article is not injected into a run.