# seiso
**A Markdown convention and linter for project docs written by AI and read by humans and agents.**
[](https://github.com/scarletkc/seiso/actions/workflows/ci.yml)
[](https://crates.io/crates/seiso)
[](https://pypi.org/project/seiso/)
[](https://www.npmjs.com/package/@scarletkc/seiso)
[](https://github.com/scarletkc/seiso/blob/main/LICENSE)
[](https://coderabbit.ai)
[](https://deepwiki.com/scarletkc/seiso)
AI writes project docs faster than anyone can review them, and coding agents
read those docs back as context for the next change. People and agents alike
take the page at its word, so a stale version number or a field list updated
in only one of its three copies misleads all of them. And AI makes the same
few mistakes over and over.
seiso defines one convention for how Markdown in a repository is organized,
the way rustfmt settled formatting for Rust code. Projects share the rules
instead of negotiating their own; each project mainly maps its documents to
kinds, and `seiso init` suggests a starting point.
## The convention
- Every document declares one kind, such as `howto`, `reference`, or `adr`,
and holds only what that kind is for. A how-to gives the steps. Why the
design looks this way belongs in an ADR.
- Each fact has one home. Other pages link to it instead of retelling it.
- Long-lived pages don't record values that change faster than the page,
such as versions, deployment status, or counts.
- A pointer names a file or symbol, so the reader doesn't have to search for
what the sentence promised.
- The finished page doesn't address whoever asked for it or narrate how it,
or the work it describes, was made.
- Judgment calls a tool can't make are written down with a reason. An
exception without one is itself a violation.
The convention is written up as a standalone
[specification](https://seiso.fog.moe/latest/convention),
with [worked examples](https://seiso.fog.moe/latest/examples)
and an [adoption guide](https://seiso.fog.moe/latest/adopting),
so a project can follow it without installing anything. The specification is
provisional before 1.0.0 and versioned separately from seiso; its direction is
open for discussion in [#37](https://github.com/scarletkc/seiso/issues/37).
seiso is the reference implementation. Its rules check documents against the
specification; stable rules run by default, and the rest are opt-in previews.
Each diagnostic says where the problem is and how to fix it, so an agent can
repair most findings from seiso's output alone. When a fix needs a judgment,
such as which of two pages owns a fact, the diagnostic names the decision.
seiso doesn't guess whether prose sounds machine-written, and it leaves
formatting and spelling to other tools.
[How seiso checks the convention](https://github.com/scarletkc/seiso/blob/main/docs/reference/convention.md)
maps each rule to the requirement it covers and the evidence it can claim.
## Install
```sh
cargo install seiso
uv tool install seiso # or: pipx install seiso
npm install -g @scarletkc/seiso
```
The PyPI and npm packages include prebuilt binaries for macOS on Apple silicon
and Intel, Linux x64 and arm64 with glibc or musl (such as Alpine), and
Windows x64 and arm64. On other platforms, use cargo; the PyPI package also
works there but builds from source, which requires a Rust toolchain. From a
source checkout, run `cargo run --