OrgDoc Runtime

OrgDoc Runtime is a local Go CLI for agents and people that need to discover document capabilities, apply an organization's brand and document rules, and produce traceable artifacts. Organization repositories can define multiple operations and brands. The selected operation chooses the brand; the renderer records the profile, capability, and input versions used for each run.

The Go core is independent of Python, media models, and network services. Optional document and media workers run in isolated environments and are installed only when needed. The existing media-report-cli Python package and media-report command remain available as the media compatibility implementation during migration.

Install OrgDoc

Download the portable .tar.gz release archive matching your operating system and architecture from the GitHub Releases page. Releases include Linux and macOS builds for amd64 and arm64; each archive contains the orgdoc executable, install and license documentation, the optional worker installer, and the portable OrgDoc agent Skill. SHA256SUMS is published alongside them. Install into a user-owned directory without administrator access; the core archive does not include Python or optional workers.

To build all supported binaries from a source checkout:

VERSION=$(cat VERSION)
RELEASE_DIR=$(mktemp -d)
scripts/check-release-version.sh "v$VERSION"
OUTPUT_DIR="$RELEASE_DIR" scripts/build-release.sh "$VERSION"
OUTPUT_DIR="$RELEASE_DIR" python scripts/package-workers.py "$VERSION"
python scripts/verify-release-assets.py "$VERSION" "$RELEASE_DIR"

To verify the core Linux archive without Python or worker executables on PATH:

scripts/smoke-release.sh "$RELEASE_DIR/orgdoc-$VERSION-linux-amd64.tar.gz"

To install and probe the worker bundles from the release assets:

scripts/smoke-worker-bundles.sh "$VERSION" "$RELEASE_DIR"

See installation details for checksum verification, install paths, supported targets, and worker setup.

Start with an organization repository

Create an organization repository from the scaffold packaged into the CLI and validate it:

orgdoc organization init --path "$HOME/orgdoc-organization"
orgdoc organization validate --organization "$HOME/orgdoc-organization" --format json
orgdoc brands list --organization "$HOME/orgdoc-organization" --format json
orgdoc capabilities list --organization "$HOME/orgdoc-organization" --format json

The example defines Henko Technologies and Henko Academy brands, several operations, invoice and narrative-report profiles, and a Humanizer skill. Each operation selects one brand explicitly. Read the product guide for the profile format and agent workflows.

Render a document

Install the invoice worker in its isolated environment, then make its entry point available on PATH:

uv sync --project workers/python/reportlab-invoice
export PATH="$PWD/workers/python/reportlab-invoice/.venv/bin:$PATH"

Render an example invoice request:

orgdoc document render \
  --organization "$HOME/orgdoc-organization" \
  --operation consulting \
  --document-type invoice \
  --input tests/fixtures/documents/invoice.json \
  --output-root ./artifacts \
  --format json

The narrative-report worker is also optional and has its own setup in the report worker guide. The CLI can render with a selected operation/brand without installing those workers; only the chosen renderer must be installed to produce its artifact.

Use the Humanizer skill

Humanizer is an agent skill, not a renderer or an automatic text-rewriting stage. Before editing narrative prose, an agent should read the organization's skills/humanizer.md, resolve the operation and brand, and respect the document type's protected_fields. Preserve amounts, identifiers, dates, quotations, citations, and typed values. When enabled by the organization, --pre-humanized-text PATH records the original prose in the run manifest. See the Humanizer policy.

Optional local media workflows

The media pack provides media-scan, media-transcription, media-report, and media-pdf capabilities. Set up only the worker environments required by a workflow:

uv sync --project workers/python/media-transcription
uv sync --project workers/python/media-report

See the media worker guide for FFmpeg, Pandoc, TeX, model, and compatibility artifact requirements. Transcription loads a model only when a transcription job starts. OrgDoc does not download models or install worker environments automatically.

Agent CLI

orgdoc --help
orgdoc --version
orgdoc organization validate --organization PATH --format json
orgdoc capabilities list --organization PATH --format json
orgdoc capabilities describe ID --organization PATH --format json
orgdoc brands list --organization PATH --format json
orgdoc context --organization PATH --operation ID --document-type ID --format json
orgdoc document render --organization PATH --operation ID --document-type ID --input INPUT.json --output-root ARTIFACTS --format json
orgdoc batch run JOBS.json --max-workers 4 --format json

Every command accepts stable JSON output where supported. Batch results preserve input order, and resource-class limits keep GPU/model and memory-heavy workers at one active job by default. The runtime guide describes request schemas and chaining media capabilities.

Compatibility and migration

The media-report command and Python distribution remain supported during the migration release. Existing commands and settings are documented in the migration guide, including the target OrgDoc command or capability and any setting that has no core replacement yet. Do not remove the Python package until a later major release after parity and migration communication.

Development

Go checks:

gofmt -w cmd internal
go vet ./...
go test ./...

Legacy Python compatibility checks:

uv sync --extra dev
uv run ruff check .
uv run ruff format --check .
uv run pytest
uv run python -m build
uv run twine check dist/*

See release checks and AGENTS.md for the migration and contribution rules.