JidoSeal CLI

Run JidoSeal's Self-Check over a folder of markdown, from your terminal, on your own machine.

Exactly what leaves your machine: nothing — 100% local, zero content egress.
Your files, their names, and their contents never leave your device.

That is not a slogan bolted onto the docs — it is the first thing the command prints, on every run, before it reads a single file. The rest of this page explains exactly what the tool does, and just as importantly what it does not do.

---

Install

One-liner:

pipx install jidoseal && jidoseal --root .

pipx is the recommended install because it puts JidoSeal in its own isolated environment, so it can neither shadow nor be shadowed by anything else on your system. If you would rather use pip, a virtual environment does the same job:

python3 -m venv ~/.venvs/jidoseal
~/.venvs/jidoseal/bin/pip install jidoseal
~/.venvs/jidoseal/bin/jidoseal --root /path/to/your/notes

From a local wheel:

python3 -m pip wheel . --no-deps -w dist-cli      # from a checkout of this repo
pipx install ./dist-cli/jidoseal-0.1.1-py3-none-any.whl

From a checkout, with no install at all:

python3 engine/local_runner.py --root /path/to/your/notes

Requires Python 3.9 or newer. Developed and exercised on 3.14.

---

Usage

jidoseal --root /path/to/your/notes

Exactly what leaves your machine: nothing — 100% local, zero content egress.
Your files, their names, and their contents never leave your device.

scanned 747 files in 1.42s — $0 · 100% local · nothing left this machine
  Bronze  coverage: 98.1%
  Silver  coverage: 84.3%
  Gold    coverage: 61.0%
manifest: /path/to/your/notes/.jidoseal/manifest.json
progress: /path/to/your/notes/.jidoseal/progress.ndjson (run scan-20260918-143012-a1b2c3)

Flag	What it does
--root <dir>	Required. The folder to scan. Every *.md beneath it, recursively.
--include-machine	Ignore the machine/transient excludes your .jidoseal/config.yaml declares, and scan every *.md under --root. With no config file there is nothing to ignore, so the flag changes nothing.
--version	Print the version and exit.
--help	Print usage and exit.

python3 -m jidoseal --root <dir> is identical to jidoseal --root <dir> — same entry point, same output, same banner.

A caution about --include-machine

The certified path does not use it. When you buy a certificate, JidoSeal scans with your configured machine excludes applied — that is the corpus definition a certificate is issued against. --include-machine is a diagnostic: useful for seeing your whole tree, but the coverage percentages it prints are not the percentages your certificate would be based on. For a number that matches, run without the flag.

What it writes

Two files, both inside <root>/.jidoseal/, both on your machine:

• manifest.json — per file: a content hash, its current tier, which governance fields are present, and exactly what is missing for Silver and Gold. This is the same artifact, in the same format, that the certified engine path produces.
• progress.ndjson — an append-only progress log, one JSON object per line, flushed to disk as each file is scanned. Append-only on purpose: a new run adds to it rather than erasing the history of previous ones.

Nothing else is written, and nothing in your corpus is modified. This command reads only.

---

Telling JidoSeal about your corpus — .jidoseal/config.yaml

Out of the box, nothing is excluded and nothing is assumed. Every *.md file under --root is scanned, apart from OKF v0.2's two reserved filenames (index.md and log.md), which the standard itself puts outside a concept corpus. No folder name is special, no owner is invented, and no document type is inferred from a directory JidoSeal has never seen.

That is deliberate. A scanner that silently drops files because their path matched somebody else's folder convention is reporting coverage over a corpus you did not choose — and the number it shows you would be wrong in a way you cannot see.

If your corpus does have conventions, tell JidoSeal about them in an optional <root>/.jidoseal/config.yaml. Every key is optional; leaving the file out is exactly the default above. The config file itself is never part of the corpus (JidoSeal only ever reads *.md), and it is read by the scan engine itself — so the CLI, the local UI and the certificate-issuing path all see the same corpus definition.

# Paths excluded as machine-generated or synced mirrors. Python regexes, matched against the
# path relative to --root. `--include-machine` ignores this list for one run.
machine_extra_excludes:
  - "^Scratch/"          # transient working notes
  - "/_drive/"           # a sync mirror — remediating it just fights the sync
  - "(?i)-autogen-"      # generated files, by filename

# Who owns a file when its frontmatter does not say. First match wins.
owner_map:
  - pattern: "^Accounts/"
    owner: "dept:finance"

# The owner for everything no rule above claims. With no `default_owner`, JidoSeal will not
# invent one — and an apply refuses rather than writing an audit line it cannot attribute.
default_owner: "human:jane-doe"

# Optional: the identity recorded on each audit-log line. Defaults to `default_owner`.
authority: "self:jane-doe"

# Extra `type` inference for your own folders, applied AFTER JidoSeal's built-in conventions
# (so a more specific built-in rule always still wins). Suggested at MEDIUM confidence, and
# never written without your explicit Apply.
propose_type_rules:
  - pattern: "^Accounts/"
    type: "finance-reference"

A malformed config is an error, not a shrug: an unknown key or a bad regex stops the run with a message naming the file, rather than quietly scanning a different corpus than you described.

Your config is recorded with the scan — and on the certificate

Every scan prints one more line:

config:   sha256:9f2c…c41d

That is a SHA-256 of your .jidoseal/config.yaml, exactly as sha256sum computes it — check it yourself:

sha256sum .jidoseal/config.yaml

With no config file, the line reads config: absent:no-config-file: running on the shipped neutral defaults is recorded as such, rather than left blank.

Why it exists: this file decides which documents are in your corpus at all, so it is part of what a tier means. A certificate is bound to a Merkle root of your files, which says WHICH files were certified but not which definition selected them — so the same digest travels onto the certificate, inside its signature. It records your corpus definition; it does not restrict it. Nothing here leaves your machine on the free path, and the digest is one-way: it carries no folder name, no path and no rule text.

---

What the tiers mean

Tiers are objective, deterministic and pass/fail. There is no judgement call and no model involved anywhere in this path — a file either has a populated field or it does not, and the same corpus scanned twice gives the same answer.

Tier	Requires
Bronze	type
Silver	Bronze, plus title, description, timestamp, owner
Gold	Silver, plus status, review_policy, reviewed_at, next_review_at

"Populated" means carrying real content. A bare title: with nothing after it earns nothing.

A file whose frontmatter fence exists but whose YAML will not parse is reported with frontmatter_ok: false. Those gaps cannot be closed by adding fields — the block has to be fixed by hand first.

---

Honest scope — what JidoSeal does and does not certify

It does:

• Certify presence and integrity of governance fields — that the metadata your documents are supposed to carry is actually there and actually populated, measured the same way every time.
• Provide hash provenance — every file's content is hashed, so the manifest is bound to the exact bytes on disk at scan time, and a later change is detectable.

It does not:

• Attribute which change broke a spec. JidoSeal will tell you that a document's governance state is what it is now, and that its content hash differs from before. It does not diff your documents or identify which edit — by you, by an agent, by anything else — was responsible.
• Judge whether your content is any good. Tiers measure governance-field presence, not quality, accuracy or usefulness of what you wrote.
• Read your prose. The scan reads frontmatter to determine fields, and hashes file bytes. No content is sent anywhere, because nothing is sent anywhere at all.

---

Exactly what leaves your machine

Nothing.

Exactly what leaves your machine: nothing — 100% local, zero content egress.
Your files, their names, and their contents never leave your device.

This is enforced structurally, not by policy:

• The installed package does not contain networking code. The wheel ships seven Python modules — the complete set the scan needs and nothing more. The engine's network-capable modules are not merely unused by this command; they are not in the distribution. You can confirm that yourself with unzip -l on the wheel, or by listing the installed files.
• Its one dependency is PyYAML, a YAML parser, used to read frontmatter. It has no network capability. See "Dependencies" below.
• Static analysis enforces it in the test suite — the modules on this path are AST-inspected for any import of socket, ssl, http, urllib, requests, httpx, aiohttp and friends, and the check fails the build if one appears.
• A runtime guard proves it on a real scan — a full scan is executed inside a harness that raises on any outbound connection or DNS lookup to a non-loopback address. It does not raise.

If you would rather trust your own eyes than our test suite: run it with a network monitor on. That is the point of a local tool.

Buying a certificate is a separate step that happens on jidoseal.com, not through this command. This CLI has no purchase path, no account, no telemetry, and no way to send anything anywhere.

---

Dependencies

One: PyYAML.

We would rather it were zero, and it is worth being precise about why it is not. JidoSeal's frontmatter parser has always used PyYAML — it is the engine's single hard requirement, and the certified engine path uses the very same parser. Replacing it would mean writing a second YAML implementation, and a second implementation is a second set of edge cases: the day it disagrees with the first about a quoted date or a multi-line string, the CLI and your certificate disagree about your corpus. A pure parser with no network capability is a much better trade than a parity risk in the thing being certified.

Everything else on the path is the Python standard library.

---

Same engine as the certificate

This is the point of the CLI, so it is worth stating plainly: jidoseal --root <dir> runs the same code the certified issuance path runs. Both call okf_manifest.build_manifest(); both tier files through the same tier_of(); both hash content the same way. The CLI is not a preview, a re-implementation or an approximation of the certified scoring — it is that scoring, invoked locally.

The practical consequence: the tiers you see in your terminal are the tiers a certificate would attest to, for the same corpus, scanned the same way (that is, without --include-machine).