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/core/           the `oaken-core` bundle and Oaken Core's console templates
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 series of self-contained prompts, one per piece of work, in docs/prompts/ (the index is docs/prompts/README.md). A prompt is a specification: what to build, what it depends on, its acceptance criteria and a report-back. You can run one with an AI coding tool or follow it by hand as a checklist; either way the tests and acceptance criteria are the contract, not the exact code any one run produces.

Files are named TRACK_NN-name.md (CORE_, CLI_, MCP_, PLUGIN_, ENRICHER_, DOCS_). The number is the prompt's permanent ID and the track says what it builds.

Not everything needs a prompt. A bug fix, a typo, a small refactor or a docs correction is an ordinary pull request: say what and why, add a test, run the checks. A prompt is for a new feature, a new plugin, or a change to an architectural decision.

Run a prompt

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 in the table below that is Open and whose dependencies are Built. If it says In progress, ask on the issue or pull request first.
3. Make a feature branch, named for the prompt: feat/28-compose-and-send. One prompt per branch and pull request is the easiest to review.
4. Start the session with: "Read docs/prompts/00-context.md, then execute docs/prompts/TRACK_NN-….md." Where a prompt and the code or the docs disagree, the code and the docs win; stop and report instead of guessing.
5. Do the work with tests (next to the code, no network), then run the checks under Development setup and Documentation.
6. Open a pull request. Paste the prompt's report-back into it. The pull request template lists what must be true before it merges.

What a pull request must update

Every prompt you run, and every change that is not one, leaves the docs true:

• Each prompt you ran gets a status block at the top of its file saying what was built and where the code differs from the prompt, and its row in the status table below.
• If you ran more than one prompt, do all of the above for each, and say in the pull request which prompts it covers.
• Everything else that mentions what you changed: the changelog, the architecture pages, the reference pages, docs/softmap.toml if you built or changed a component, and config.example.toml for a new setting. Search for the old behaviour and fix every mention.
• If you move or rename a doc, update its references. Do not do it by hand: run uv run python docs/tools/move_doc.py OLD NEW (--dry-run first if you like). It does the git mv and fixes Markdown links, paths and bare names everywhere, including the moved file's own links. Then rebuild the site. check_docs.py fails on any prompt reference that dangles, and on an index or status table that is out of step with the files.

Ask for a feature

If you want something that has no prompt, open a feature request and write the prompt in it (the template shows how, and docs/prompts/TEMPLATE.md is the format). Then:

1. A maintainer reads it. The outcomes are approved, changes asked for, or declined with a reason. The labels are prompt: proposed, prompt: approved and prompt: declined.
2. When it is approved, a pull request adds it as docs/prompts/TRACK_NN-name.md with the next free number, status Open, a row in the index and in the status table. You can open that pull request or a maintainer will. Now anyone can run it.

Change a prompt

Anyone can propose a change to a prompt with a pull request, and the pull request is where the design is discussed. Architectural considerations live in two places: the prompts and the ADRs.

• Before it is built (Proposed, Written or Open): edit the prompt. If you change a decision it records, say why in the pull request.
• A decision that outlives one prompt (a rule, a trade-off, a surface that must not change) is an ADR in docs/adr/, linked from the prompt.
• After it is built the prompt is a record. Do not rewrite history to match the code: add to its status block where the code deviates, and describe how the thing works now in docs/architecture/.
• A prompt is reviewed like code. It is a set of instructions an AI will carry out, so a prompt must not tell it to fetch from the network, run a script nobody has reviewed, or switch off or skip a check. A reviewer rejects one that does.

Status of the prompts

As of 2026-10-24 (commit 65d3a9f plus the 0.1.1 branch). Proposed is a feature request with a prompt in it, waiting for approval (it is not in this table yet). Open is approved and free to take. In progress has someone on it. 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.

Grouped by track; the number is the permanent ID, so it runs across all tables.

CORE

CLI

MCP

PLUGIN

ENRICHER

DOCS

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).