Skip to content

Contributing to KruxOS

KruxOS community-extensible directories — packs/, plugins/, themes/, and docs/public/ are licensed under Apache 2.0.

For the streamlined version of this page, see the repo root's CONTRIBUTING.md.

Ways to contribute

Contribution Where Available
Bug reports + feature requests GitHub Issues now
Documentation improvements (docs/public/) Pull requests to the public repo now
Capability packs (packs/) Pack development flow now
Dashboard themes (themes/) Theme system ships v0.0.3 v0.0.3
Extension plugins (plugins/) Plugin runtime ships v0.0.3 v0.0.3
Community discussion KruxOS Discord now

Working on docs

The public docs are built with mkdocs Material. Preview your changes locally before opening a PR:

git clone https://github.com/altvale/kruxos.git
cd kruxos/docs/public
pip install mkdocs mkdocs-material
mkdocs serve
# browse http://localhost:8000

The live site at docs.kruxos.com is built from the same source with the same theme — what you see locally is what readers will see.

Style

  • Concrete, literal, AI-readable prose. Capability descriptions especially should avoid metaphors — agents read these descriptions to decide which tool to call.
  • Match the existing cadence of nearby pages rather than introducing new section structures.

Working on capability packs

The pack development flow — @kruxos/pack-sdk, registry-based publishing, scaffolded examples — is live. Develop packs locally against a running appliance or publish to the community registry:

# On a running appliance, after building your pack directory:
kruxos pack install /path/to/my-pack

The pack-development documentation lives under developers/packs/ and describes the runtime contract for handlers and the YAML capability definitions.

Pull request flow

  1. Fork the public repo and clone your fork.
  2. Branch off main: git checkout -b docs/typo-fix-in-quickstart.
  3. Make your changes (follow the prose style above for docs).
  4. Open a PR against main with a clear description of what changed and why.

PR guidelines

  • One change per PR — typo fixes, clarification PRs, additional examples should each be their own PR.
  • For docs PRs: render with mkdocs serve and click through the affected pages before opening the PR.
  • For pack PRs (v0.0.2+): include the YAML capability definition, the handler implementation, and at least one example invocation in the PR description.

Reporting security issues

To report a security vulnerability, email security@altvale.com. Do not file a public issue. See SECURITY.md for the disclosure timeline.

License

By contributing to packs/, plugins/, themes/, or docs/public/, you agree that your contribution is licensed under Apache 2.0 — the same license as the surrounding directory.