> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lilfella.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Contributing

> Make a focused app change and verify the claims it affects.

# 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](https://github.com/Avijit-Kumar-GIT/fella/blob/main/docs/DEV_SETUP.md) lists platform packages and provider setup.

```bash filename="terminal" theme={null}
git clone https://github.com/Avijit-Kumar-GIT/fella
cd fella
pnpm install
pnpm tauri dev
```

## Make a focused app change

<Steps>
  <Step title="Read the maintained boundary">
    Start with the [architecture](https://github.com/Avijit-Kumar-GIT/fella/blob/main/docs/ARCHITECTURE.md), [design rules](https://github.com/Avijit-Kumar-GIT/fella/blob/main/docs/DESIGN.md), [non-goals](https://github.com/Avijit-Kumar-GIT/fella/blob/main/docs/NON-GOALS.md), and [extension contract](https://github.com/Avijit-Kumar-GIT/fella/blob/main/docs/EXTENSIBILITY.md).
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Run all four gates">
    Run the commands below with the default SQLite features.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Required local gates

```bash filename="from src-tauri" theme={null}
cargo test --locked
cargo clippy --all-targets --locked -- -D warnings
```

```bash filename="from repository root" theme={null}
pnpm run check
pnpm run build
```

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:

```bash filename="from repository root" theme={null}
bash scripts/check-byok-test-surface.sh
```

## 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`](https://github.com/Avijit-Kumar-GIT/fella/blob/main/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`](https://github.com/Avijit-Kumar-GIT/fella/blob/main/CONTRIBUTING.md) and the PR template.

## Next steps

<CardGroup cols={2}>
  <Card title="Choose a test layer" icon="test-tube" href="/other-resources/evaluation">
    Match deterministic tests and live evaluation to the claim.
  </Card>

  <Card title="Read the release boundary" icon="book-open" href="https://github.com/Avijit-Kumar-GIT/fella/blob/main/docs/LEAN-PERSONAL-RELEASE.md">
    See which capabilities are active in the personal release.
  </Card>
</CardGroup>