olenji 1.0.0__tar.gz

olenji-1.0.0/.editorconfig

@@ -0,0 +1,19 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 4
+trim_trailing_whitespace = true
+
+[*.{json,yml,yaml,js,cjs,mjs,html,css}]
+indent_size = 2
+
+[*.md]
+# Two trailing spaces can intentionally encode a Markdown line break.
+trim_trailing_whitespace = false
+
+[Makefile]
+indent_style = tab

olenji-1.0.0/.gitattributes

@@ -0,0 +1,39 @@
+# The source archive and wheel must see the same bytes on every host.
+* text=auto
+*.py text eol=lf
+*.pyi text eol=lf
+*.js text eol=lf
+*.cjs text eol=lf
+*.mjs text eol=lf
+*.html text eol=lf
+*.css text eol=lf
+*.svg text eol=lf
+*.swift text eol=lf
+*.md text eol=lf
+*.toml text eol=lf
+*.json text eol=lf
+*.yml text eol=lf
+*.yaml text eol=lf
+*.xml text eol=lf
+*.plist text eol=lf
+*.lock text eol=lf
+*.resolved text eol=lf
+LICENSE text eol=lf
+.gitignore text eol=lf
+.gitattributes text eol=lf
+.editorconfig text eol=lf
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.wav binary
+*.flac binary
+*.mp3 binary
+*.mp4 binary
+*.zip binary
+*.gz binary
+*.tgz binary
+*.whl binary
+
+# Accepted application distributions retain their exact published checksums.
+/dist/** -text

olenji-1.0.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,41 @@
+name: Bug report
+description: Report a reproducible application, installation or compatibility problem.
+body:
+  - type: markdown
+    attributes:
+      value: |
+        For a suspected vulnerability, follow SECURITY.md instead of posting exploit details here.
+        Share a small synthetic or public reproduction. Remove API keys, pairing links, private transcripts, recordings and identifying local paths from diagnostics.
+  - type: input
+    id: version
+    attributes:
+      label: Olenji version and installation route
+      description: Include the version, source/wheel/npm route, and commit or artifact hash if available.
+    validations:
+      required: true
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: OS/version, architecture, Python; Node/Bun for npm; browser/model/backend if involved. State whether the problem occurs on native hardware or in a container.
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to reproduce
+      description: Exact commands or actions, minimal input and any relevant options. Use placeholders for credentials and returned IDs.
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected and actual behavior
+      description: Include the structured error code and exit status when available.
+    validations:
+      required: true
+  - type: textarea
+    id: evidence
+    attributes:
+      label: Sanitized evidence and workarounds
+      description: Relevant log excerpts, prior working version, reproducibility, or a small public fixture. Review doctor output before sharing it.

olenji-1.0.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: true

olenji-1.0.0/.github/ISSUE_TEMPLATE/documentation.yml

@@ -0,0 +1,21 @@
+name: Documentation or first-run problem
+description: Help improve an unclear, incorrect or missing instruction.
+body:
+  - type: input
+    id: page
+    attributes:
+      label: Document or command
+      description: File, section, command help or first-run step.
+    validations:
+      required: true
+  - type: textarea
+    id: problem
+    attributes:
+      label: What was unclear or incorrect?
+      description: Include your platform and installation route where relevant. Share sanitized command output only.
+    validations:
+      required: true
+  - type: textarea
+    id: suggestion
+    attributes:
+      label: Suggested clarification

olenji-1.0.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,22 @@
+name: Feature or improvement
+description: Describe a workflow, usability gap, model adapter or performance need.
+body:
+  - type: textarea
+    id: need
+    attributes:
+      label: Workflow and problem
+      description: What are you or your agent trying to accomplish, and what currently blocks it?
+    validations:
+      required: true
+  - type: textarea
+    id: outcome
+    attributes:
+      label: Desired outcome
+      description: Describe the observable behavior. For models, include the exact public model identity and intended hardware.
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives and constraints
+      description: Existing commands you tried, compatibility/privacy needs, and useful measurements. Do not attach private audio or credentials.

olenji-1.0.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,19 @@
+## Problem and resulting behavior
+
+Explain the concrete problem, what changes, and the result for users or agents.
+
+## Verification
+
+List the commands and focused checks you executed. Name the OS, architecture and runtime where they matter. Distinguish controlled fixtures from installed-package, native model or physical-device execution, and identify remaining gates.
+
+For behavioral changes, identify the regression the test detects and its independent expected result. Explain any controlled external boundary. If you remove or consolidate a test, say where its distinct protection remains. Use `docs/TESTING.md`; test-count increases are not evidence of quality. Documentation-only changes can report the relevant source/link check.
+
+## Compatibility and documentation
+
+Describe changes to CLI/MCP/API behavior, source revisions, workspace schema, model identity, installation or process ownership. Link the relevant documentation update when the change affects contributors or users.
+
+- [ ] I reviewed the contribution and code-of-conduct documents.
+- [ ] The change contains no private recordings, transcripts, credentials, pairing links or downloaded model weights.
+- [ ] I have the right to contribute the included code and any fixtures under the project's documented terms.
+
+For a suspected vulnerability, follow `SECURITY.md` and keep exploit details out of public pull requests.

olenji-1.0.0/.github/dependabot.yml

@@ -0,0 +1,24 @@
+version: 2
+updates:
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    groups:
+      python-patch-updates:
+        update-types: [patch]
+  - package-ecosystem: npm
+    directory: /tests/browser
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 3
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 3
+
+# The npm launcher has no external JavaScript dependencies.
+# Native model/runtime pins have compatibility-specific tests and are reviewed
+# deliberately; this configuration does not change them or auto-merge updates.

olenji-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,219 @@
+name: verify
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+permissions:
+  contents: read
+concurrency:
+  group: verify-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+env:
+  UV_VERSION: '0.13.4'
+jobs:
+  quality:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    env:
+      UV_CACHE_DIR: ${{ runner.temp }}/olenji-quality-cache
+      UV_PROJECT_ENVIRONMENT: ${{ runner.temp }}/olenji-quality-environment
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: '3.12'
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: '24'
+      - run: python -m pip install uv==${{ env.UV_VERSION }}
+      - name: Install only the isolated quality tools
+        run: uv sync --frozen --only-group quality
+      - name: Check source, metadata and workflow policy
+        run: uv run --frozen --only-group quality python scripts/check_quality.py --report quality-results.json
+      - name: Check the bundled handbook against reviewed source
+        run: python scripts/sync_handbook.py
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        if: always()
+        with:
+          name: source-quality
+          path: quality-results.json
+          retention-days: 14
+  python:
+    needs: quality
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - {os: ubuntu-22.04, python: '3.11', arch: x64}
+          - {os: ubuntu-24.04, python: '3.12', arch: x64}
+          - {os: ubuntu-24.04, python: '3.13', arch: x64}
+          - {os: ubuntu-24.04, python: '3.14', arch: x64}
+          - {os: ubuntu-24.04-arm, python: '3.12', arch: arm64}
+          - {os: macos-15, python: '3.12', arch: arm64}
+          - {os: macos-15-intel, python: '3.12', arch: x64}
+          - {os: macos-26, python: '3.12', arch: arm64}
+          - {os: windows-2022, python: '3.12', arch: x64}
+          - {os: windows-11-arm, python: '3.12', arch: arm64}
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 25
+    env:
+      UV_CACHE_DIR: ${{ runner.temp }}/olenji-uv-cache
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: ${{ matrix.python }}
+          architecture: ${{ matrix.arch }}
+      - if: runner.os == 'Linux'
+        run: sudo apt-get update && sudo apt-get install -y ffmpeg libportaudio2
+      - if: runner.os == 'macOS'
+        run: brew install ffmpeg portaudio
+      - if: runner.os == 'Windows'
+        run: choco install ffmpeg -y --no-progress --limit-output
+      - name: Install reviewed build runner
+        shell: python
+        run: |
+          import os, subprocess, sys
+          subprocess.run([sys.executable, '-m', 'pip', 'install', 'uv==' + os.environ['UV_VERSION']], check=True)
+      - run: uv sync --frozen --extra dev --group release
+      - name: Require audio decode tools
+        run: uv run --frozen --extra dev --group release python -c "import shutil; assert shutil.which('ffmpeg') and shutil.which('ffprobe')"
+      - run: uv run --frozen --extra dev --group release pytest --junitxml=test-results.xml
+      - run: uv run --frozen --extra dev --group release python -m build --no-isolation
+      - name: Verify the installed wheel in a fresh environment
+        shell: python
+        run: |
+          import os, pathlib, subprocess, sys
+          source = pathlib.Path.cwd()
+          environment = pathlib.Path(os.environ['RUNNER_TEMP']) / 'olenji-wheel-check'
+          subprocess.run(['uv', 'venv', '--python', sys.executable, str(environment)], check=True)
+          python = environment / ('Scripts/python.exe' if os.name == 'nt' else 'bin/python')
+          wheel = next((source / 'dist').glob('*.whl'))
+          requirements = environment / 'default-requirements.txt'
+          subprocess.run(['uv', 'export', '--frozen', '--no-default-groups', '--no-emit-project',
+                          '--format', 'requirements-txt', '--output-file', str(requirements)], check=True)
+          subprocess.run(['uv', 'pip', 'sync', '--python', str(python), '--require-hashes',
+                          '--only-binary', ':all:', '--link-mode', 'copy', str(requirements)], check=True)
+          subprocess.run(['uv', 'pip', 'install', '--python', str(python), '--no-deps', str(wheel)], check=True)
+          subprocess.run(['uv', 'pip', 'check', '--python', str(python)], check=True)
+          subprocess.run([str(python), str(source / 'tests/smoke_installed.py'), '--source-root', str(source),
+                          '--report', str(source / 'installed-wheel-results.json')], cwd=os.environ['RUNNER_TEMP'], check=True, timeout=240)
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        if: always()
+        with:
+          name: verify-${{ matrix.os }}-${{ matrix.arch }}-${{ matrix.python }}
+          path: |
+            dist/*
+            test-results.xml
+            installed-wheel-results.json
+          retention-days: 14
+  distribution:
+    needs: quality
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-24.04, macos-15, windows-2022]
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 25
+    env:
+      UV_CACHE_DIR: ${{ runner.temp }}/olenji-release-cache
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: '3.12'
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: '24'
+      - if: runner.os == 'Linux'
+        run: sudo apt-get update && sudo apt-get install -y ffmpeg libportaudio2
+      - if: runner.os == 'macOS'
+        run: brew install ffmpeg portaudio
+      - if: runner.os == 'Windows'
+        run: choco install ffmpeg -y --no-progress --limit-output
+      - run: python -m pip install uv==${{ env.UV_VERSION }}
+      - run: uv sync --frozen --extra dev --group release
+      - name: Verify the npm launcher without dependency installs
+        run: node --test --test-timeout=20000 packages/npm/test/runtime.test.mjs
+      - name: Use the commit timestamp for reproducible archives
+        shell: python
+        run: |
+          import os, subprocess
+          epoch = subprocess.check_output(['git', 'show', '-s', '--format=%ct', 'HEAD'], text=True).strip()
+          with open(os.environ['GITHUB_ENV'], 'a', encoding='utf-8') as stream:
+              stream.write('SOURCE_DATE_EPOCH=' + epoch + '\n')
+      - name: Build and verify Python and npm artifacts
+        run: uv run --frozen --extra dev --group release python scripts/build_release.py
+      - name: Install the sdist and npm tarball outside the checkout
+        run: uv run --frozen --extra dev --group release python tests/smoke_distribution.py --artifacts dist --source-root . --report distribution-installed-results.json
+      - name: Verify final artifact checksums
+        run: uv run --frozen --extra dev --group release python scripts/build_release.py --verify dist
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        if: always()
+        with:
+          name: distribution-${{ matrix.os }}
+          path: |
+            dist/*
+            distribution-installed-results.json
+          retention-days: 14
+  apple-compile:
+    needs: quality
+    runs-on: macos-26
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          persist-credentials: false
+      - name: Confirm native toolchain
+        run: swift --version && xcrun --show-sdk-version
+      - run: swift build --package-path native/apple --configuration release --force-resolved-versions
+      - run: swiftc olenji/native/ScreenCapture.swift -o "$RUNNER_TEMP/olenji-screencapture"
+      - name: Preserve compile result
+        run: swift build --package-path native/apple --configuration release --show-bin-path --force-resolved-versions > apple-build-location.txt
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: apple-compile-evidence
+          path: apple-build-location.txt
+          retention-days: 14
+  browser:
+    needs: quality
+    runs-on: ubuntu-24.04
+    timeout-minutes: 25
+    env:
+      UV_CACHE_DIR: ${{ runner.temp }}/olenji-uv-cache
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: '3.12'
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: '22'
+      - run: sudo apt-get update && sudo apt-get install -y ffmpeg libportaudio2
+      - run: python -m pip install uv==${{ env.UV_VERSION }}
+      - run: uv sync --frozen --extra dev
+      - run: npm ci --ignore-scripts
+        working-directory: tests/browser
+      - run: npm test
+        working-directory: tests/browser
+      - run: npx playwright install --with-deps chromium firefox webkit
+        working-directory: tests/browser
+      - name: Run three native browser engines against the real service
+        env:
+          OLENJI_PYTHON: ${{ github.workspace }}/.venv/bin/python
+          OLENJI_PERF_TURNS: '10000'
+        run: node tests/browser/cross-engine-smoke.cjs
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        if: always()
+        with:
+          name: native-browser-results
+          path: docs/validation/browser-cross-engine.json
+          retention-days: 14

olenji-1.0.0/.gitignore

@@ -0,0 +1,58 @@
+.venv/
+__pycache__/
+.pytest_cache/
+*.egg-info/
+dist/
+build/
+.coverage
+*.db
+*.db-wal
+*.db-shm
+node_modules/
+.DS_Store
+.ruff_cache/
+
+# Local credentials and disposable application workspaces.
+.env
+.env.*
+!.env.example
+api.token
+/data/
+/state/
+/recordings/
+/models/
+/runtime/
+/downloads/
+/exports/
+/logs/
+
+# Accidental root-level media/model inputs; deliberate tests/fixtures stay visible.
+/*.wav
+/*.flac
+/*.mp3
+/*.m4a
+/*.mp4
+/*.mov
+/*.gguf
+/*.onnx
+/*.safetensors
+
+# Local verification reports; reviewed docs/validation evidence stays visible.
+/quality-results.json
+/test-results.xml
+/*-results.json
+/host-*.json
+/host-*.xml
+/apple-build-location.txt
+
+# Exact reviewed development release required by the outer website builder.
+# New filenames remain ignored until a deliberate release review updates this list.
+!/dist/
+/dist/*
+!/dist/SHA256SUMS
+!/dist/runtime-requirements.txt
+!/dist/release-manifest.json
+!/dist/olenji-1.0.0-py3-none-any.whl
+!/dist/olenji-1.0.0.tgz
+!/dist/olenji-1.0.0.zip
+!/dist/olenji-1.0.0.tar.gz

olenji-1.0.0/AGENTS.md

@@ -0,0 +1,78 @@
+# Working on Olenji
+
+## Hosting policy — owner instruction, 12 October 2026
+
+All project hosting and associated services must use Hetzner, including production, staging, previews, demos, public reviews/evidence, runtimes, databases, uploads and static/large assets. Vercel deployments or managed services require direct, explicit owner approval for this specific project, environment and service; existing configuration and historical instructions do not supply approval. Do not deploy, upload, provision or enable automatic Vercel deployments without it. Read-only investigation and exports for migration are allowed.
+
+Preserve exact release artifacts, data, environment differences and historical review links during migration. Verify Hetzner delivery and rollback before cutover, and change only migration-scoped DNS after verification. Preserve domain registration, unrelated DNS and unrelated services. Carry this policy into deployment documentation and other execution hosts. This application currently supports a private loopback service rather than a public server.
+
+## Development
+
+Read `docs/HANDOFF.md`, `CONTRACT.md` and the relevant implementation before changing a behavior. `docs/ARCHITECTURE.md` records the current language and distribution decisions. `docs/VALIDATION.md` distinguishes current execution from historical evidence.
+
+## Start
+
+- Use standard CPython 3.12 for the default development and model-runtime path.
+- Restore development dependencies with `uv sync --frozen --extra dev`; update `uv.lock` deliberately when dependency metadata changes.
+- Read `CONTRIBUTING.md` for review expectations and `SECURITY.md` before reporting a suspected vulnerability. Keep private reproductions out of ordinary public issues.
+- Run the read-only quality gate with `uv run --frozen --extra dev --group quality python scripts/check_quality.py`. The `quality` group adds pinned tooling without replacing the normal development dependencies.
+- Run relevant Python regressions with `uv run --frozen --extra dev pytest tests/test_<area>.py`. Run the complete suite before a release artifact is finalized.
+- Browser regression commands are in `tests/browser/README.md`. npm launcher commands are in `packages/npm/README.md`.
+- Build/release commands and registry prerequisites are in `docs/RELEASING.md`. Building an artifact does not publish it.
+
+## Code map
+
+| Responsibility | Location |
+| --- | --- |
+| Application version | `olenji/__init__.py` |
+| Agent CLI, transport and shared views | `olenji/cli.py`, `client.py`, `mcp.py`, `views.py` |
+| Shared locks, cancellation and network policy | `olenji/locking.py`, `cancellation.py`, `network.py` |
+| Local service, jobs and API | `olenji/service.py`, `runtime.py`, `app.py`, `schemas.py` |
+| Durable source, translations and events | `olenji/store.py` |
+| Automatic translation recovery and provider calls | `olenji/automatic_translations.py`, `translations.py` |
+| Model identity/install/runtime | `olenji/catalog.py`, `models.py`, `inference.py`, `engines.py`, `engine_worker.py` |
+| Capture and recognition lifecycle | `olenji/audio.py`, `pipeline.py`, `diarization.py`, `processes.py` |
+| Browser and incremental exports | `olenji/web/`, `exports.py`, `export_files.py` |
+| Apple framework helpers | `native/apple/`, `olenji/native/` |
+| npm launcher and explicit setup | `packages/npm/` |
+| Packaging and checksums | `scripts/`, `pyproject.toml`, `uv.lock` |
+
+## Preserve the contracts
+
+- Keep one Python application engine. npm launches the same wheel; it must not grow an independent model catalog or state implementation.
+- Run `python scripts/check_architecture.py` after dependency changes. Shared helpers must not import service startup or a frontend. Deferred imports are dependencies too.
+- Keep help/version lightweight, stdout suitable for agent JSON/MCP, diagnostics on stderr and subprocess arguments shell-free.
+- Keep source revisions, translation groups, human corrections and event cursor consistency intact. Add a failing regression for a reproduced state or lifecycle defect before fixing it where practical.
+- Treat capture sources, child processes, model leases, temporary audio and export files as owned resources through success, cancellation and failure.
+- Keep critical queues and protocol records bounded. Do not solve overload by silently dropping committed text or fabricating audio/timestamps.
+- Preserve exact model identities and compatibility restrictions. Never claim installation or real inference from a catalog entry or a mocked test.
+- The application version has one source. Keep API/database versions independent; test migrations and preserve recovery backups.
+- Ordinary commands may not silently bootstrap runtimes, download models or restart a recording during an upgrade.
+- Preserve Unicode and platform-neutral paths. Windows process/locking tests on Linux do not replace native Windows execution.
+
+## Verify the thing being changed
+
+Use `docs/TESTING.md` to choose the owning test and an independent expected result. Strengthen an existing weak case before adding duplicate coverage. Negative checks need successful setup and a positive content/result assertion where absence alone could pass. Coordinate race tests at the actual boundary, own teardown on failure, and keep background-thread/unraisable errors fatal. Test counts and coverage percentages are not targets; retain distinct contracts and document the replacement when consolidating a test.
+
+Use focused checks during implementation. Release validation must also run an installed wheel outside the checkout and verify all bundled resources. Distribution changes must exercise the packed npm tarball and wheel built from the source archive. Native backend changes need real inference when the relevant runtime/hardware is available; otherwise record the exact remaining gate.
+
+Do not relabel historical timing, browser, OS or model results as evidence for a new build. Record fixture size, host, sample count, exact implementation/artifact identity and whether a check was mocked, synthetic or native. Keep substantive performance comparisons byte-equivalent where output should be unchanged.
+
+Avoid broad formatting/framework/language migrations without a concrete benefit. Add dependencies only where they solve an identified need and preserve the supported package matrix. Update adjacent docs and the handoff when an interface, installation step or known limit changes.
+
+Keep contribution/security/conduct guidance and the unreleased changelog accurate. Repository protections, contacts, registry provenance and native host results need actual configuration or execution; a policy file or CI definition alone is not evidence that they are enabled or passed. The boundary review map is in `docs/SECURITY_MODEL.md`.
+
+Release source and packages must exclude virtual environments, dependency directories, caches, private state, credentials, recordings and model weights. Publishing requires the actual repository and registry ownership configuration; do not fabricate those values or publish as part of an ordinary improvement pass.
+
+## Maintain the shipped handbook
+
+The user-facing source is `docs/handbook/chapters/`; the browser and `olenji docs`
+read its generated copy in `olenji/web/handbook.html`. Edit the chapters alongside
+user-facing code. Review the changed implementation and public-interface diff;
+then update `source-provenance.json` and the reference inventory deliberately.
+Do not refresh hashes merely to silence a check. Rebuild with
+`python docs/handbook/tools/build_docs.py`, run its source verifier, then
+`python scripts/sync_handbook.py --write`. The read-only command without `--write`
+is required in CI and in the release tests. It rejects code or chapter changes
+that lack a reviewed matching handbook. PDF generation remains a development
+step; ordinary help uses only the standard library and bundled HTML.