Contributing

Start with the repository environment

Keating uses Bun with a Devenv-managed toolchain. Root and web packages have separate responsibilities, and namespaced Devenv tasks provide the build and verification entry points. Read the repository's current agent guidance and development documentation before choosing commands.

Use a clean checkout or preserve existing work when contributing. A successful isolated component check is useful evidence, but it does not establish that the complete application builds or deploys.

devenv shell
devenv tasks run keating:install
devenv tasks list
devenv tasks run keating:web

Choose the layer that owns the behavior

Root TypeScript uses NodeNext-style .js import extensions. Web code uses bundler resolution and its established aliases. Keep provider-specific execution behind adapters and account authority outside the pedagogy engine.

• Core artifacts and CLI: src/core and src/cli; deterministic teaching operations belong below the UI.
• Browser UI and teaching adapters: web/src/components, web/src/hooks, and web/src/keating.
• Shared interaction and account contracts: packages/learner-contracts and shared.
• Terminal host: src/tui; native mobile client: mobile; desktop host and bridges: desktop.
• Teaching experiments and revision gates: shared/evolution; evaluation protocols and evidence notes: docs/teaching-evolution.md.

Change shared behavior across its consumers

A new learner interaction needs more than a browser component. Define its semantic contract and action result, then update source mapping, validation, web/mobile/terminal rendering, state restoration, and parity fixtures. When a core command signature changes, update generated help and browser parity where relevant.

For storage changes, version the schema, preserve readable legacy data, and test upgrade, blocked-tab, quota, and write-failure behavior. For course submissions, preserve the distinction between local save and remote delivery.

Verify the boundary you changed

Prefer tests of behavior and system invariants over snapshots that repeat the implementation. Keep deterministic tests independent of hosted inference by injecting model runners and judges at explicit boundaries. Exercise cancellation, persistence, authorization, and failure paths when they are part of the change.

A web production build includes Vite and Nitro; a frontend-only bundle does not prove API routes work. A mobile bundle is not a device login test. A deployed container is not proof of a successful provider exchange. State exactly which checks completed and which integration boundary remains unverified.

devenv tasks run keating:test
devenv tasks run keating:test-web
devenv tasks run keating:web-build
devenv tasks run keating:mobile-check

Make the result reviewable

Describe the learner or developer problem, the resulting behavior, and the evidence for the change. Include a concrete before-and-after example when it helps. Separate implementation status from release availability, and link to the source or experiment artifact behind consequential claims.

Do not commit generated runtime state, credentials, local build output, or private learner records. Releases use the repository's Bun version workflow and synchronized manifests; a documentation or UI contribution does not require publishing a release.