Skip to content
CloseYourItdocsPages
Back to the siteENITSelf-host

Documentation / Using CloseYourIt

Knowledge base

Write notes, decisions and guides for your projects, find them by meaning and ask questions with sources.

The knowledge base holds what the team knows about a project: notes, decisions taken, guides. Pages can be found by meaning, not only by exact words, and they show up as suggestions next to tickets and errors.

You find it in the menu under Knowledge. Its entry page leads to three places, in the order you use them: Review, the pages, the Collections.

Write a page

  1. Open the pages and press New page.
  2. Pick the Kind: Note, Decision or Guide.
  3. Pick the Projects or Groups it belongs to. A page can sit in several projects.
  4. Write the Content in markdown, in plain words. Technical details go in the Technical section, which is optional.
  5. Press Save. Shortly after, the page enters search and the assistant can use it to answer.

Readers see two tabs: Simple and Technical. Every change creates a version: from Version history you read old versions and bring one back with Restore. The current one stays in the history.

Without projects or groups, the page applies to the whole organization. Only people with full access can create it, and only they can see it.

To point to another page, write its title between double square brackets: [[Kamal deploy]]. While you type, the app suggests titles that exist. When you save, it becomes a link.

  • In the Links box of every page you find Links to (the pages it points to) and Linked from (the pages that cite it).
  • If you rename the target page, the link keeps working.
  • If the title does not exist yet, it stays plain text. No broken links.

Collections

A collection puts several pages in a row, like a manual: the index on the left, the open page on the right.

  1. Open Collections and press New collection.
  2. Give it a title and pick projects or groups.
  3. In Collection pages, pick the pages. The order you pick them in is the order of the index.

A collection can hold pages from different projects. A page sits in one collection only. If you delete the collection, the pages stay.

Type in the search box of the list. By default you search by meaning: you find the right page even when it uses other words. To search for the exact words, anywhere in the text, press Search by exact words instead.

Search by meaning needs a connected AI service (see AI). If there is none, or it does not answer, search uses exact words and says so.

Ask a question

Open Ask a question, write your question and press Ask. The answer uses only the pages of the projects you can see, and it cites the pages it comes from. If the pages are not enough, it says so instead of making things up.

On the same page you find examples to start from (Try asking) and the Team's recent questions.

From the terminal you do the same with the CLI:

cyi kb search deploy rollback          # search by meaning
cyi kb ask how do we roll back a deploy
cyi kb show <id> --related             # a page and the ones to read next

Pages proposed by an assistant

While it works, an assistant may notice something worth keeping: an error it solved, a decision, a trap. It does not publish it: it proposes it and waits for a person.

A proposal that is waiting does not show up in search, in answers or in the suggestions next to tickets.

  1. Open Review. At the top you see how many proposals are waiting.
  2. Read the title, the reason and the text of the proposal.
  3. Press Accept to keep it: it becomes visible to everyone and enters search and answers.
  4. Press Discard if it is not useful. It is not deleted: it stays aside, and an assistant will not propose the same note to you again.

To accept or discard you need permission to edit the knowledge base. A person always decides: an automated login is refused.

From the terminal, with your personal login:

cyi kb approve <id>
cyi kb reject <id>

An assistant (or you) proposes a page with --in-review. --review-note is the line that explains why it is worth keeping:

cyi kb create -p acme-api --title "Rollback" --body-file ./note.md \
  --in-review --review-note "Hit it today, not obvious from the code"

A proposal must have its text in plain words. If the text is technical, the details go in the technical section (--tech-spec-file); otherwise the proposal is refused.

The automatic reviewer

When it is on, an automatic reviewer reads every page before it is saved. If the page does not follow the knowledge base rules, it is not saved and a message says what to fix. A proposal the reviewer sends back stays in Review, marked Sent back by the reviewer: fix it, save it, then accept it.

Who wrote the page

Pages written by an assistant carry the Assistant mark, even after you accept them. The Written by filter of the list finds them. The mark goes away when a person really rewrites the text: fixing a comma or changing the tags is not enough.

Reread old pages

Decisions and guides get old. Each one has a date by which it should be reread: six months for a decision, one year for a guide. Notes do not expire.

After that date the page can still be found, but it is marked To review. In Review, section To reread, press Still true if it is. If you fix the page instead, the date restarts on its own.