Skip to content

Dodaios is an open-source agent OS for your desktop: it runs your coding agents, browser and apps by voice or chat, on your own machine. Formerly Personal Jarvis.

docs: make GitHub landing page welcoming to maintainers

Ruben Lütkecf9234fe2a39
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
index a3174c8b42..ba03868cad 100644
--- a/.github/ISSUE_TEMPLATE/config.yml
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -2,7 +2,7 @@ blank_issues_enabled: true
contact_links:
- name: Questions & community (Discord)
url: https://discord.gg/x7USduHxbc
- about: Usage questions, setup help, and general chat. Fastest answer, usually same day.
+ about: Usage questions, setup help, and general chat.
- name: Ideas & design discussion
url: https://github.com/PersonalJarvis/PersonalJarvis/discussions
about: Propose a feature, ask how something is meant to work, or float an approach before you build it.
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index f340dd69dc..24bda3dae5 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -11,7 +11,7 @@ the same evidence as a new speech provider, and we do not pretend otherwise.
## Related issue
-<!-- "Closes #123", or "none" if there isn't one. Small fixes don't need an issue first. -->
+<!-- "Closes #123", or "none" if there isn't one. Small fixes don't need an issue first. For larger changes, link the design discussion. -->
---
@@ -28,7 +28,8 @@ the same evidence as a new speech provider, and we do not pretend otherwise.
<details open>
<summary><b>Docs, comments, or translations only</b></summary>
-- [ ] Nothing else. Open it — this is the whole checklist.
+- [ ] Links and media touched by this change resolve in the rendered page.
+- [ ] Public text contains no personal data or credentials.
</details>
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 79b37bbdaf..3ab43ff4ab 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,242 +1,110 @@
-<p align="center">
- <a href="https://github.com/PersonalJarvis/PersonalJarvis">
- <img src="assets/brand/banner.png" alt="Personal Jarvis" width="520" />
- </a>
-</p>
+# Contributing to Personal Jarvis
-<h1 align="center">Contributing</h1>
+Personal Jarvis is a cross-platform desktop application for voice, agents, and
+connected tools. We welcome focused fixes, tests, accessibility work, platform
+reports, and documentation improvements. The useful first step is a problem you
+can reproduce and explain; familiarity with the whole repository is not required.
-<p align="center">
- Thanks for being here. Small PRs, friendly review, same-day help on Discord.<br />
- Everything you need to get started fits on this screen.
-</p>
+## Choose a first contribution
-<p align="center">
- <a href="https://github.com/PersonalJarvis/PersonalJarvis/pulls"><img alt="PRs welcome" src="https://img.shields.io/badge/PRs-welcome-FFD60A?style=flat-square&labelColor=0A0A0A" /></a>
- <a href="https://github.com/PersonalJarvis/PersonalJarvis/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22"><img alt="Good first issues" src="https://img.shields.io/badge/good%20first%20issues-open-FFD60A?style=flat-square&labelColor=0A0A0A" /></a>
- <a href="https://discord.gg/x7USduHxbc"><img alt="Discord" src="https://img.shields.io/badge/Discord-join-FFD60A?style=flat-square&logo=discord&logoColor=0A0A0A&labelColor=0A0A0A" /></a>
- <a href="LICENSE"><img alt="License: Apache 2.0" src="https://img.shields.io/badge/License-Apache_2.0-FFD60A?style=flat-square&labelColor=0A0A0A" /></a>
-</p>
-
----
-
-## Your first PR in five steps
-
-1. **Fork and clone**, then install:
- ```bash
- pip install -e . --no-deps && pip install -r requirements.txt && pip install -e ".[dev]"
- ```
-2. **Pick something.** A [good first issue](https://github.com/PersonalJarvis/PersonalJarvis/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22), or simply the thing that annoyed you.
-3. **Change one thing** and run `pytest -m "not slow"` (UI work: `npm run test` in `jarvis/ui/web/frontend/`).
-4. **Open the PR.** The template has one short block per kind of change — tick yours, skip the rest. A typo fix owes nothing else.
-5. **Stuck?** Ask on [Discord](https://discord.gg/x7USduHxbc). Someone usually answers the same day.
-
-That's it. You don't need to read the rest of this page to open a PR, and you don't need to
-understand the whole system to fix one piece of it.
-
-> [!TIP]
-> **A first PR doesn't have to be perfect.** If CI fails on a rule you've never heard of,
-> that's normal and not a rejection — say so in the PR and we'll walk you through it.
-
----
-
-## Two things worth knowing
-
-- **We write in English.** Code, comments, docs, commit messages and PR text are English so
- that everyone can read them. Talk to us in any language you like — the repo itself stays
- English, and CI checks that for you so you don't have to think about it.
-- **Keep each PR to one change.** Small PRs get reviewed fast and merged fast.
-
----
-
-## What we'd love help with
-
-| | |
+| Starting point | A useful, reviewable result |
|---|---|
-| **Bug fixes** | Always first. Crashes, wrong behaviour, lost data, anything that made the voice path worse. |
-| **Cross-platform work** | Linux, macOS, Windows and headless servers are equal here. Making something work on a platform it didn't before is a great contribution. |
-| **Security hardening** | Prompt injection, the line between what the user said and what a tool observed, path traversal. See [`SECURITY.md`](SECURITY.md). |
-| **Speed and robustness** | Voice latency, retries, honest degradation, the rule that a conversation never blocks. |
-| **New providers and plugins** | Across all seven groups (wake, STT, TTS, brain, harness, tool, channel). Provider-agnostic, passing the contract suite. |
-| **Docs** | Any time. Unclear sentence, missing step, outdated screenshot — fix it. |
+| [Open bugs](https://github.com/PersonalJarvis/PersonalJarvis/issues?q=is%3Aissue%20is%3Aopen%20label%3Abug) | Confirm an issue still reproduces on current `main`, add a focused regression test, and fix it. Comment on the issue before starting if its scope is unclear. |
+| Installation or product docs | Follow one documented path on a named OS, then correct the exact step that differs from reality. Include the command, observed result, and working replacement. |
+| Desktop accessibility | Improve one keyboard, focus, or screen-reader interaction in `jarvis/ui/web/frontend/src/`. Show the before/after behavior in light and dark mode. |
+| Platform parity | Test one existing feature on Windows, macOS, Linux, or a headless host, then submit a reproducible report or a narrow fix. Check [OS parity](docs/os-parity.md) first. |
+
+Use [GitHub Issues](https://github.com/PersonalJarvis/PersonalJarvis/issues/new/choose)
+for a concrete bug or task. For a larger design, use
+[Discussions](https://github.com/PersonalJarvis/PersonalJarvis/discussions) to
+agree on scope before implementing it. You can open a small, self-contained PR
+without an issue. The `good first issue` label is used when a specific task has
+been scoped; browse open bugs or propose a small task if that list is empty.
+
+Interested in helping maintain an area over time? Name the subsystem and the
+kind of testing or review you can provide in a Discussion. A series of scoped
+contributions gives everyone a concrete basis for deciding how to collaborate;
+repository owners handle review, merge, and access decisions.
+
+## Find your way around
+
+| Area | Start here |
+|---|---|
+| Core contracts and events | `jarvis/core/protocols.py`, `jarvis/core/events.py` |
+| Desktop and web UI | `jarvis/ui/web/frontend/`; backend routes in `jarvis/ui/web/` |
+| Realtime voice | `jarvis/realtime/` and its focused tests |
+| Providers and plugins | `jarvis/plugins/`, entry points in `pyproject.toml`, `tests/contract/` |
+| Tests and fixtures | `tests/`, especially `tests/fakes/` |
-> [!TIP]
-> Planning something bigger than a fix? Open an issue first so we can agree on the approach.
-> It keeps you from writing a PR that was never going to land.
+Read the [architecture overview](docs/architecture-overview.md) for the system
+map, [architecture decisions](docs/adr/) for past choices, and
+[AGENTS.md](AGENTS.md) for the binding engineering rules. In particular, new
+capabilities must work across supported operating systems and must not depend
+on one model provider or one developer's machine.
----
+## Development setup
-## Dev setup
+Use Python 3.11+ and Git. From your fork or a local checkout:
```bash
-git clone https://github.com/PersonalJarvis/PersonalJarvis ~/personal-jarvis
-cd ~/personal-jarvis
-
python -m venv .venv
-source .venv/bin/activate # Windows: .\.venv\Scripts\Activate.ps1
-
-pip install -e . --no-deps # activates the plugin entry-points
-pip install -r requirements.txt # runtime dependencies
-pip install -e ".[dev]" # pytest, ruff, mypy
-
-python -m jarvis --wizard # interactive first-run setup
-python -m jarvis.ui.web.launcher # run it (add --headless for a server)
+# macOS/Linux: source .venv/bin/activate
+# Windows PowerShell: .\.venv\Scripts\Activate.ps1
+python -m pip install -e . --no-deps
+python -m pip install -r requirements.txt
+python -m pip install -e ".[dev]"
+python -c "import jarvis; print(jarvis.__file__)"
```
-Frontend: `npm install` in `jarvis/ui/web/frontend/`, then `npm run dev` / `npm run build` /
-`npm run test`.
-
-> [!NOTE]
-> After editing entry-points in `pyproject.toml`, re-run `pip install -e . --no-deps`. That is
-> what activates new plugins, and skipping it is the #1 reason a plugin "does not exist".
+The import path must point into this checkout. Re-run
+`python -m pip install -e . --no-deps` after changing plugin entry points.
+For an isolated desktop test, use `run-dev.bat` on Windows or `./run-dev.sh`
+on macOS/Linux. Both launch a development instance with its own data and ports.
+`--headless` runs the API without a desktop shell. The desktop and voice paths
+need the relevant OS permissions and hardware; you can work on tests and docs
+without them.
-### Running the checks
-
-```bash
-pytest -m "not slow" # fast subset — enough for most PRs
-pytest tests/ # full suite
-pytest tests/contract/ -v # for new STT/Brain/Tool/Channel providers
+For frontend work, run `npm install` in `jarvis/ui/web/frontend/`, then
+`npm run test` and `npm run build` there. The desktop loads built frontend
+files and reloads them automatically; do not commit generated
+`jarvis/ui/web/dist/` files.
-ruff check jarvis/ && ruff format --check jarvis/
-mypy jarvis/
-
-cd jarvis/ui/web/frontend && npm run test && npm run build
-```
+## Test and review the change
-Tests use fakes from `tests/fakes/`, not mocks.
+Keep a PR to one logical change. Describe the user-visible behavior, why it
+changes, and how you verified it. Include the OS and provider when they matter.
+Use the [PR template](.github/PULL_REQUEST_TEMPLATE.md) for the evidence that
+matches your change:
----
-
-## Before you open the PR
-
-The PR template scales with what you touched. Find your row, ignore the rest:
-
-| Your change | What it owes |
+| Change | Verification to include |
|---|---|
-| Docs, comments, translations | Nothing beyond English |
-| Web UI | `npm run test` + `npm run build`, works in light **and** dark mode, a screenshot. Don't commit `jarvis/ui/web/dist/` — the maintainer rebuilds the bundle |
-| Bug fix, ordinary Python | `pytest -m "not slow"` green, a test for the fixed behaviour, `ruff` clean |
-| New provider | The above plus `pytest tests/contract/`, no `import jarvis.*` in the module, honest degradation without a key |
-| A shared contract (capability, config schema, turn-taking, credentials, OS backend) | The above plus: which platforms you touched and what the others do now, a boot on headless `python:3.11-slim`, `CHANGELOG.md` |
-
-Unsure which row you're in? Open the PR and ask. We'd rather tell you in review than have
-you guess high and waste an evening.
-
-Describe what changed and why, link the issue it closes. By contributing you agree your work
-is licensed under the [Apache License 2.0](LICENSE) — see
-[`docs/licensing.md`](docs/licensing.md).
-
----
+| Docs or one local view | Check rendered links and media, or show the view in light and dark mode. |
+| Existing backend, provider, or OS adapter | Run the focused tests for that family; state which supported cells you exercised and how the others behave. |
+| Shared capability or contract | Add contract tests, cover Windows/macOS/Linux behind capability checks, update `docs/os-parity.md`, and verify a fresh install with one supported key. See the T3 rules in `AGENTS.md`. |
-## Going deeper
+Useful local commands, selected by the change:
-Reference for when you want it. None of this is required for a first PR.
-
-<details>
-<summary><b>The architecture in four rules</b></summary>
-
-<br />
-
-Personal Jarvis is an 8-layer system. Four rules matter before you write anything:
-
-1. **Layers talk through protocols.** Higher layers reach lower ones only through
- `jarvis/core/protocols.py`. Anything sideways goes over the EventBus as a typed,
- immutable event.
-2. **Everything streams.** `Brain`, `STT`, `TTS` and `Harness` methods return an
- `AsyncIterator`; a provider that cannot stream yields exactly one element.
-3. **No vendor is load-bearing.** Never hardcode one brain provider; `cfg.brain.primary`
- decides.
-4. **The router dispatches rather than doing.** Heavy work becomes a mission in an isolated
- `git worktree`, under a worker-and-critic loop.
-
-For the deep version read [`docs/LLM-CONTEXT.md`](docs/LLM-CONTEXT.md) (a dense
-engineering snapshot) and [`CLAUDE.md`](CLAUDE.md) (the binding conventions, including the
-cross-platform doctrine in section 2).
-
-</details>
-
-<details>
-<summary><b>Plugin, tool, or skill?</b></summary>
-
-<br />
-
-The most common design question. Pick the smallest thing that fits:
-
-| | Plugin | Tool | Skill |
-|---|---|---|---|
-| What it is | A swappable provider | A brain-callable action inside one turn | An authored, multi-step workflow |
-| Where it lives | `jarvis/plugins/<group>/`, one of 7 groups | Registered tool, run via `ToolExecutor` | Authored skill; generated ones start as `draft` |
-| The one rule | No `import jarvis.*` in the module; new STT/Brain/Tool/Channel must pass `tests/contract/` | Never call `Tool.execute()` directly | Never auto-activated |
-
-A swappable backend is a plugin. A single action the brain can call is a tool. A multi-step
-workflow somebody wrote down is a skill.
-
-**Marketplace plugins** (the connectors in the app's Plugins store — GitHub, Notion, Slack, …)
-are a separate, fourth thing. New submissions are packaged per the vendor-neutral
-[Agent Plugins standard v1.0.0](https://agent-plugins.org/): a directory with a
-`plugin.json`, an `mcp.json` when the service has an MCP server, and everything
-Jarvis-specific under the `io.github.personaljarvis` extension namespace. Field mapping and
-the migration tracker: [`docs/marketplace/agent-plugins-standard.md`](docs/marketplace/agent-plugins-standard.md).
-
-</details>
-
-<details>
-<summary><b>Adding a TTS provider: four registrations, not one</b></summary>
-
-<br />
-
-The entry point in `pyproject.toml` makes a TTS provider discoverable, but the config path
-builds providers through `_build_provider()` in
-[`jarvis/plugins/tts/__init__.py`](jarvis/plugins/tts/__init__.py) — that is where each
-family's own voice, model and sub-table handling lives, and where leftover values from a
-previous provider get scrubbed. A provider with an entry point but no branch there hits the
-`Unknown TTS provider` fallback: Gemini speaks instead of you, with only a log line to say so.
-
-The four places:
-
-1. The entry point in `pyproject.toml`.
-2. A branch in `_build_provider()`.
-3. An alias set wired into `_canonical_tts_name()`, so every spelling of your provider
- resolves to one family.
-4. An entry in `_TTS_SECRET_CANDIDATES` if it needs a key — without it the credential gate
- treats the provider as always available.
-
-</details>
-
-<details>
-<summary><b>Conventions CI enforces</b></summary>
-
-<br />
-
-You'll find out either way; better to know first:
+```bash
+pytest tests/path/to/relevant_test.py
+pytest tests/contract/
+pytest tests/
+ruff check jarvis/
+ruff format --check jarvis/
+mypy jarvis/
+```
-| Area | The rule |
-|---|---|
-| Language | English artifacts only (`language-policy` gate) |
-| Risk tier | `ToolExecutor.execute()` is the only authorized execution path |
-| Router | `ROUTER_TOOLS` is a frozenset; no spawn tool in a worker tool set |
-| Enum drift | Strings crossing module boundaries use the five-layer pattern plus a parity test |
-| Config writes | Mutate `jarvis.toml` only via `config_writer` (lock, tempfile, BOM-safe) |
-| Subprocess | Always pass `NO_WINDOW_CREATIONFLAGS` |
-| Secrets | Only via `get_secret()`; never in code, config, or commits |
-| Dependencies | No Windows-only or GPU-only dependency in the base install; extras only |
-
-The full anti-pattern register lives in [`docs/LLM-CONTEXT.md`](docs/LLM-CONTEXT.md).
-
-</details>
-
----
-
-## Community
-
-<p align="center">
- <a href="https://discord.gg/x7USduHxbc"><img alt="Discord" src="https://img.shields.io/badge/Discord-join_the_server-FFD60A?style=for-the-badge&logo=discord&logoColor=0A0A0A&labelColor=0A0A0A" /></a>
- <a href="https://x.com/Ruben_Luetke"><img alt="X" src="https://img.shields.io/badge/X-follow-FFD60A?style=for-the-badge&logo=x&logoColor=0A0A0A&labelColor=0A0A0A" /></a>
-</p>
-
-<p align="center">
- <a href="https://discord.gg/x7USduHxbc">Discord</a> ·
- <a href="https://x.com/Ruben_Luetke">X</a> ·
- <a href="https://github.com/PersonalJarvis/PersonalJarvis/issues">Issues</a> ·
- <a href="CODE_OF_CONDUCT.md">Code of conduct</a>
-</p>
+Tests use `tests/fakes/` rather than `unittest.mock`. Some repository-wide
+checks may have existing failures; report the exact command and failure instead
+of claiming a full pass from focused tests. For code that runs at startup, also
+run `python scripts/ci/check_boot_budget.py`.
+
+AI-assisted contributions are welcome when the author can explain the diff,
+verify its behavior, and respond to review. Write committed code, comments,
+documentation, logs, and commit messages in English. Keep secrets and personal
+data out of the repository and PR. Contributions are licensed under
+[Apache 2.0](LICENSE); see [licensing details](docs/licensing.md).
+
+For private security reports, follow [SECURITY.md](SECURITY.md). For conduct
+concerns, see [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md). Usage questions belong
+in [Discord](https://discord.gg/x7USduHxbc) or
+[Discussions](https://github.com/PersonalJarvis/PersonalJarvis/discussions).
diff --git a/README.md b/README.md
index 4fd7d2f42c..c6bc57292c 100644
--- a/README.md
+++ b/README.md
@@ -46,6 +46,14 @@ and [how the system fits together](#how-it-works).
[Discord](https://discord.gg/x7USduHxbc) · [X](https://x.com/Ruben_Luetke) ·
[Instagram](https://www.instagram.com/personaljarvis/)
+**Build with us.** Personal Jarvis spans a Python/FastAPI backend, a React/TypeScript
+desktop interface, voice, agents, and OS integrations. If you want to improve a
+specific part and help maintain it over time, start with a scoped issue or PR.
+[Choose a contribution](https://github.com/PersonalJarvis/PersonalJarvis/blob/main/CONTRIBUTING.md#choose-a-first-contribution) ·
+[Set up a development checkout](https://github.com/PersonalJarvis/PersonalJarvis/blob/main/CONTRIBUTING.md#development-setup) ·
+[See the architecture](https://github.com/PersonalJarvis/PersonalJarvis/blob/main/docs/architecture-overview.md) ·
+[Discuss an approach](https://github.com/PersonalJarvis/PersonalJarvis/discussions)
+
## Install
**Windows — PowerShell**
@@ -420,21 +428,21 @@ Open **Docs** in the app for searchable product guides, or follow the topics her
| [Architecture decisions](https://github.com/PersonalJarvis/PersonalJarvis/tree/main/docs/adr/) | Design decisions and their context. |
| [README media source](https://github.com/PersonalJarvis/PersonalJarvis/blob/main/scripts/readme-video/README.md) | Provenance, example data, still previews, and rendering commands. |
-## Community and contributing
-
-Follow the project on the [website](https://personaljarvis.ai),
-[X](https://x.com/Ruben_Luetke), and
-[Instagram](https://www.instagram.com/personaljarvis/).
-
-Questions, ideas, and bug reports are welcome on [Discord](https://discord.gg/x7USduHxbc)
-and [GitHub](https://github.com/PersonalJarvis/PersonalJarvis/issues/new/choose).
-Watch walkthroughs on the [Personal Jarvis channel](https://www.youtube.com/@PersonalJarvis).
-
-Read [CONTRIBUTING.md](https://github.com/PersonalJarvis/PersonalJarvis/blob/main/CONTRIBUTING.md) before a pull request. Hardware reports,
-provider integrations, accessibility improvements, and native-language feedback
-are especially useful. AI-assisted contributions are welcome; review focuses
-on the change and its evidence. Repository contributions are written in English.
-Report vulnerabilities privately through [SECURITY.md](https://github.com/PersonalJarvis/PersonalJarvis/blob/main/SECURITY.md).
+## Build with us
+
+Contributions are useful across desktop accessibility, platform support,
+voice reliability, provider integrations, tests, and documentation. The
+[contributor guide](https://github.com/PersonalJarvis/PersonalJarvis/blob/main/CONTRIBUTING.md)
+maps those areas to code, a development setup, and review expectations. A small,
+reproducible improvement is a good place to begin; you do not need to understand
+the entire application first.
+
+Use [issues](https://github.com/PersonalJarvis/PersonalJarvis/issues) for bugs
+and scoped work, and [Discussions](https://github.com/PersonalJarvis/PersonalJarvis/discussions)
+to agree on a larger design or offer sustained help in a subsystem. AI-assisted
+contributions are welcome when the author can explain and verify the result.
+Repository contributions are written in English. Report vulnerabilities
+privately through the [security policy](https://github.com/PersonalJarvis/PersonalJarvis/blob/main/SECURITY.md).
## Contributors