Contributing

You need Python 3.11 or newer and uv.

uv sync
uv run ruff check
uv run ruff format --check
uv run mypy
uv run pytest

Install the git hooks (lint plus secret scan) with uv run pre-commit install if you use pre-commit, or run uv run detect-secrets-hook --baseline .secrets.baseline <files>.

Oaken reads a single config.toml. It lives outside the repo, in the per-user config directory (via platformdirs):

Set OAKEN_HOME=/some/dir to relocate everything under one root (<dir>/config/config.toml). Precedence is: built-in defaults < config.toml < OAKEN_* environment variables. Unknown top-level keys are an error; every section has defaults, so you only set what you change.

config.example.toml at the repo root is a documented template covering every section (Gmail, IMAP, SMTP, Ollama, AI models, sync, API, logging). Copy it and edit:

cp config.example.toml ~/.config/oaken/config.toml

Secrets never go in config.toml. OAuth refresh tokens and IMAP/SMTP passwords live in the OS keyring (service oaken, user <kind>:<account>). The file only names the Gmail OAuth client JSON; the token is obtained by the authorization flow. For Gmail, bring your own OAuth client (Desktop-app type, gmail.modify scope) and publish it to Production — a Testing-mode app expires refresh tokens after ~7 days.

src/oaken/           core: the daemon, API, operations, storage, ingest (the `oaken` package)
src/oaken_*/         first-party plugins (providers, embedder, enrichers, vector store)
apps/cli/            the `oaken` command, a separate package (`oaken-cli`, import `oaken_cli`)
apps/webui/          the web UI (templates today; its own app later)
docs/                the documentation site sources and generators

Core knows nothing about the apps. An app is a client of core's HTTP API and lives in its own uv workspace member with its own pyproject.toml, so it can be built, versioned and tested on its own (uv run pytest apps/cli). See ADR 0006.

• Every Python file starts with # SPDX-License-Identifier: Apache-2.0.
• Tests live in a tests/ directory next to the code they cover (src/oaken/core/tests/ for src/oaken/core/, apps/cli/src/oaken_cli/tests/ for the CLI). Run uv run pytest from the repo root for everything, or from any subdirectory to run only the tests below it. tests/ at the root holds repo-wide checks.
• Tests never use the network, Ollama, Gmail, Docker or real mail. Use synthetic fixtures.
• Never commit real email content, addresses, databases or tokens.
• Use Conventional Commits for commit messages.
• AI-assisted contributions must follow the AI tooling rules below.

Contributions produced with generative AI tooling must follow the ASF's Generative Tooling Guidance. In short:

• You still represent that the contribution is your original creation and that you are entitled to license it under Apache-2.0 (ICLA §§4–5). Disclose any third-party material it contains.
• Make sure the tool's terms grant you rights broad enough to contribute the output under Apache-2.0, and don't restrict it in ways inconsistent with the Open Source Definition.
• Do not include GPL or otherwise Apache-incompatible third-party code (this matches our "no GPL dependencies" rule). Where a tool can report similarity to its training data, or a code scanner is available, use it to gain reasonable certainty no copyrighted material was copied.
• Record the tool in the commit message with a provenance trailer, for example Co-authored-by: <Tool> <Version> or Generated-by: <Tool> <Version>.
• Public-facing AI-generated text (the docs site, the published demo, release notes, announcements, security advisories) must be reviewed by a committer before publishing, or be labeled as AI-generated (EU AI Act). Reviewing it as you would any other contribution is enough.

Oaken Mail is built from a numbered series of self-contained prompts, one per session, in docs/prompts/ (the index is docs/prompts/README.md). Each one says what to build, what it depends on, its acceptance criteria and a report-back checkpoint. You can run one by hand or with an AI coding tool, and anyone can take an Open one.

To run one:

1. Read docs/prompts/00-context.md (the rules and the decisions already taken), this guide, the ADRs and the architecture page for the part you touch.
2. Pick a prompt below that is Open and whose dependencies are Built. If it says In progress, ask on the issue or pull request first: somebody is already on it.
3. Start the session with: "Read docs/prompts/00-context.md, then execute docs/prompts/NN-….md." Where a prompt and the code or the docs disagree, the code and the docs win; stop and report instead of guessing.
4. Do the work with tests (next to the code, no network), then run the checks under Development setup and Documentation.
5. In the same pull request, update the table below (and docs/softmap.toml if you built or changed a component). A prompt that is built but still marked Open sends the next contributor to redo it.

Status of the prompts

As of 2026-10-21 (commit 7ee6308). Built means the prompt's deliverables are in main with tests. Partly says what is done and what is left. A Written prompt has a plan and no code yet.

Not written yet, on purpose: a legacy-database importer, packaging (systemd, launchd, installers), at-rest encryption, plugin sandboxing, and embedding-throughput tuning on CPU.

The project website is generated locally from the Markdown in docs/ and the generated HTML is committed beside it; GitHub Pages serves the main branch's /docs folder. CI does not build it. After changing docs (or the software map), regenerate, check and commit the result:

uv run --group docs python docs/tools/build_site.py           # regenerate the HTML in docs/
uv run --group docs python docs/tools/check_docs.py           # links, anchors, and "HTML is up to date"
uv run --group docs python docs/tools/build_site.py --out /tmp/preview --serve   # optional preview

check_docs.py (and CI) fails if the committed HTML differs from a fresh build. The build records what it generated in docs/.site-manifest and only ever replaces those files.

Register new pages in docs/site.toml. Keep the software map current: edit docs/softmap.toml in the same change that builds or alters a component (the build fails if it disagrees with the repository).