Skip to main content

​
Contribute without widening the base by accident

Fella accepts app changes in this repository. The current personal release has one maintained contribution surface: the application and its fixed local analytics path. The former extension design is archived for future forks.

​
Choose a contribution lane

| Change | Review expectation | | --- | --- | --- | | Bug fix, UI, engine, verification, provider, parser, or built-in tool | App tests, design boundaries, and binary impact | | New file format | Parser and fixture tests | | Sandbox or resource-limit change | Boundary-focused tests and a security review | If an idea needs a new tool, network path, filesystem capability, or generated workspace artifact, open an issue first so the product boundary can be reviewed.

​
Prepare the development environment

  • Rust 1.93 or newer.
  • Node 22 or newer. CI currently uses Node 24.
  • pnpm 11.
  • Tauri system dependencies; Linux requires GTK 3 and WebKitGTK 4.1 development packages.
  • A model provider only for live app/evaluation work; deterministic tests do not need one.
The developer setup guide lists platform packages and provider setup.

​
Make a focused app change

1

Read the maintained boundary

Start with the architecture, design rules, non-goals, and extension contract.
2

Choose the smallest implementation

Preserve the fixed base tool set and normal read-only analytics path. Prefer a focused parser, check, or interaction improvement over a parallel feature surface.
3

Add the matching test

Use a deterministic fixture for engine behavior and a reproducible eval case only when the claim depends on model interpretation. Do not treat one live provider response as a regression test.
4

Run all four gates

Run the commands below with the default SQLite features.
5

Document changed claims

Update maintained architecture when structure changes and add a dated decision entry when a design decision changes. Keep benchmark fixture, generator, and grader changes together.

​
Required local gates

Do not add --features duckdb to the normal gate. DuckDB is neither built nor tested by CI; it is an opt-in backend with known parity gaps and a resource-heavy bundled build. The test and benchmark surface is BYOK-only. Run the guard when adding a model fixture or evaluation entry point:

​
Security review prompts

Before opening a PR, ask:
  • Does this expose a new filesystem or network path?
  • Can model-controlled input reach a shell, Python, URL, SQL, or renderer?
  • Does it change which prompt or tool result a hosted provider sees?
  • Does it store a credential in auth.json rather than settings, browser storage, or transcripts?
  • Does a read-only claim need qualification for Python or user-authored context?
  • Does a verification change detect semantic errors, or only grounding/replay patterns?
State the actual boundary in docs and tests rather than broadening a guarantee.

​
Experimental boundary

The /mcp command is retained as an inert signpost. It does not connect to a service or add tools in the personal release. The active user-authored context surface is the root fella.md file. Pack, augment, and connector designs are archived in docs/EXTENSIBILITY.md for future custom forks.

​
Open the pull request

  1. Branch from main and keep one logical change per PR.
  2. Use the repository’s Conventional Commit style, such as fix(agent): ... or docs: ....
  3. Explain the user outcome, contribution lane, design boundary, and verification performed.
  4. Include tests and maintained documentation updates in the same PR.
  5. Follow CONTRIBUTING.md and the PR template.

​
Next steps

Choose a test layer

Match deterministic tests and live evaluation to the claim.

Read the release boundary

See which capabilities are active in the personal release.