Maintain the Olenji documentation
Edit one source, publish matching versions
Use the Google developer documentation style guide. Start with the reader's task, explain prerequisites, give the shortest complete procedure, and state the result. Use the same word for the same feature. Explain an unavoidable technical term at first use. Keep internal implementation detail in the companion reference unless it changes a user's decision.
For each feature, answer: How can I do it? What must I choose? What gets saved? What could leave the computer? How do I know it finished? How do I recover if it fails?
Avoid changing numeric test totals, model totals, or platform claims merely to match a new release announcement. Review the actual source and evidence.
Keep code and documentation in the same change
Follow Keep documentation current for every application change. The change checker requires updated instructions or a specific explanation that user behavior is unchanged. Its decision is tied to the exact changed files. The repository integration steps explain how to make the checks required in CI; those hosted settings are not changed by this bundle.
Build
Use a separate documentation environment with the pinned tools listed in documentation-tools.txt. WeasyPrint also needs its host's text-layout libraries. Font files are not included in this package.
python tools/build_docs.py
python tools/doc_build_state.py
python tools/check_functions.py --with-outputs
The build produces readable Markdown, offline HTML, a complete PDF, and the same functions list as a standalone PDF/HTML/Markdown. Do not maintain a second feature list: edit chapters/00-functions.md once. functions-map.json assigns every recorded CLI command and agent tool to a reader-facing group; update it after reviewing an interface change. The checker also protects the separately listed file, live-input, and translation routes, the complete-workflow paths, and the final sharing checklist. It verifies matching generated items. Update the full task instructions when changing a completion or recovery condition; do not improve the overview while leaving the task chapter behind. A correct mapping does not by itself prove each prose claim; review the instructions and actual source as well. The builder records its maintained inputs and generated outputs in documentation-build.json. The freshness check fails after a chapter, example, reviewed inventory, build tool, or generated file changes. It does not replace source or behavior verification.
HTML requires no remote fonts, analytics, or JavaScript. The PDF includes linked contents and bookmarks. All links between guide and reference sections become internal links in the combined PDF.
Check the reviewed source
Run in an environment that can import the target application and the documentation tools:
python tools/verify_docs.py --source /absolute/path/to/olenji --report evidence/documentation-checks.json
This command does not start the service, download models, use a microphone, call a provider, or alter the expected source fingerprint. It rejects changes to reviewed source files before importing the application. It also compares detailed parser options, full model records, tool schemas, settings, and public schemas—not just item counts.
The checker parses shell examples with the real parser, validates the shipped JSON files against their declared schemas, checks navigation, and checks reference completeness. A syntactically valid example is not proof that its model runs on every OS.
Run the focused tests
The target application's normal dependencies must be available. Add the documentation tools and test tools in a separate environment. The PDF build also needs the host text-layout libraries; the browser test needs a local Chromium executable.
Set OLENJI_SOURCE to the extracted app source in your shell before running:
python -m pytest tests -q
The checker tests and authored-text workflow tests do not download models or call providers. For the browser fix, follow source-fix/README.md and run its four scenarios against separate baseline and patched source directories. Baseline failures at the saved-false assertion are expected; do not mix them into a passing-suite total.
To recheck the generated documents, run:
python tools/check_presentation.py
This checks HTML/PDF navigation, PDF text bounds, and offline desktop/mobile reading behavior. Review rendered pages as well; an automated geometry check cannot replace visual inspection.
Review a new build deliberately
-
Keep the old source fingerprint and evidence.
-
Obtain the actual new source archive and record its identity.
-
Extract a candidate interface inventory to a new file:
python tools/inspect_source.py --source /absolute/path/to/new-source --output candidate-inventory.json -
Review the diff. Recheck defaults, file ownership, privacy choices, source and translation relationships, and supported hardware in code.
-
Update affected chapters and example files together. Update provenance only after the review; the verifier must never do that for you.
-
Run the example, behavioral, checker-negative, and presentation tests. Preserve failed-before/passed-after evidence for real fixes.
-
Rebuild and open the PDF and HTML. Check code wrapping, tables, keyboard navigation, and actual section destinations.
Do not reuse this edition's hardware or inference claims for a newer source archive. Distinguish current runs from historical tests bundled with the application.
Keep tests meaningful
Tests should detect a plausible wrong instruction or harmful default. The documentation journey uses the shipped JSON examples and real storage/API behavior to check source preservation, stale translations, exports, and deletion. The separate upload test checks the browser's selected value and submitted form data, with explicit user overrides.
The checker tests intentionally introduce an invalid flag, a malformed example, a broken link, a changed model detail, and a changed source fingerprint. Valid controls still have to pass. A test count alone is never a quality target.
Apply the optional source fix
Read source-fix/README.md. The fix is not silently applied by building or reading the documentation. It checks the exact reviewed input hash and refuses an unknown or newer app file, preventing an old patch from overwriting later work.
Writing reference
The documentation is written using Google's developer documentation style guidance: task-oriented procedures, explicit results, consistent terms, and plain language. No accessibility certification or formal conformance claim is made. Relevant editorial sources: clear language, procedures, and word choices.
Review the handbook without an application checkout
For an editorial-only update, the recorded-interface check can catch accidental changes to command examples, model/tool listings, and JSON templates:
python tools/check_recorded_contracts.py --report evidence/recorded-contracts.json
python -m pytest tests/test_documentation_workflow.py tests/test_reader_checks.py
This checks the documentation against the saved review evidence and schema
inventory. It does not run the application's command parser or its additional
validation rules. Do not report it as fresh source verification. When application
code changes or new command examples are introduced, use verify_docs.py against
the actual matching source before publication.
The current editorial edition is recorded in edition.json. Preserve
source-provenance.json and historical reports until the underlying source is
actually re-reviewed. New reports belong in a separate evidence directory.