Use cases / Project documentation

Stop re-explaining your project.

Keep architecture, conventions, and decisions beside the code so people and coding agents can find the same context.

Put the context beside the code

Architecture: how components fit together.
Decisions: why you chose an approach.
Conventions: what people and agents must follow.

Use setup to adopt existing docs. For a new wiki, let your installed agent inspect the repository and write the first pages.

Create, then find one real answer

okn setup

Example session · choosing your source

◆ Select knowledge sources
  1. docs/  (3 Markdown files)
Select comma-separated numbers [1]: 1

Choose your files, then create a managed copy or adopt a directory. Setup shows the plan before writing.

okn search Wiki "what context affects citation validation?"

Example output · demo excerpt

Source: `conventions/citations-and-sources.md:23-29`

- Keep structural validation deterministic.
- Return a stable reason code for each rejected value.
- Do not make source reliability decisions in code.

Relevant project conventions arrive with the file and line range they came from.

okn view Wiki

Example output · local address varies

Open Knowledge view: http://127.0.0.1:4185/wiki/
root /your-project/Wiki
Press Ctrl+C to stop.

Opens the local viewer in your browser so you can browse, search, and edit the Markdown.

The search question comes from the demo below. For your own project, replace it with a question your docs should answer. Replace Wiki if you chose another path.

Keep it with the change

okn check Wiki

Example output · abbreviated healthy wiki

Knowledge status

Structure       READY
Links           READY
Freshness       NOT CONFIGURED
Retrieval       NOT CONFIGURED
Overall         READY

Structure and links pass. Freshness and retrieval checks stay optional until you configure them.

okn review Wiki

Example output · copied review task excerpt

# Open Knowledge Content Review

Review scope: `changed`
Deterministic validation: 0 errors, 0 warnings.

Treat findings as advisory.

Choose an installed agent, copy the task, or save it. The task guides a review; it is not a completed review result.

Review changed docs after a code change. Update the affected architecture or decision page, then commit code and knowledge together. Agent review is optional and requires your configured agent.

Explore the example

Open the project documentation demo. It contains real Markdown pages, working links, and local search.

Open demo wiki Read editorial workflow View source files

Set up your knowledge base

Follow the setup guide Explore other workflows