> For the complete documentation index, see [llms.txt](https://docs.revault.onepub.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.revault.onepub.dev/docs/rust_development.md).

# Rust Development Guidance

This project follows local security and storage invariants first, then general Rust idioms.

## References

Use these as the baseline:

* Rust API Guidelines: <https://rust-lang.github.io/api-guidelines/>
* Clippy documentation: <https://doc.rust-lang.org/clippy/>
* Clippy lint list: <https://rust-lang.github.io/rust-clippy/master/>

For a published skill-style reference, use the OpenClaw Rust skill as a light checklist for ownership, borrowing, strings, errors, iterators, concurrency, and unsafe pitfalls:

* <https://playbooks.com/skills/openclaw/skills/rust>

Do not import a generic implementation skill wholesale. It will miss project rules around page-cache ownership, secret ownership, COW redaction, and recovery.

## Required Checks

Run from `rust/`:

```
bash tools/check_required.sh
```

This script runs formatting, hard Clippy, and tests for the active Rust crates: `lockbox_core`, `lockbox_cli`, and `lockbox_vault`.

When a new Rust crate becomes part of the supported build, add it to `tools/check_required.sh`, `tools/clippy_advisory.sh`, and the CI workflow.

Hard Clippy means:

```
cargo clippy -p lockbox_core -p lockbox_cli -p lockbox_vault --all-targets -- -D warnings
```

That treats Clippy's default lint groups as errors. It is required, but it is not the strongest possible Clippy policy.

## API Docs

Generate the public `lockbox_core` API docs from `rust/`:

```
bash tools/generate_api_docs.sh
```

The generated entry point is `rust/target/doc/lockbox_core/index.html`. The generated HTML is build output and is not committed.

## Advisory Clippy

Run from `rust/`:

```
bash tools/clippy_advisory.sh
```

This enables `clippy::pedantic`, `clippy::nursery`, and `clippy::cargo` as warnings, with noisy metadata/visibility lints disabled. Treat the output as review input, especially for public API, parser, crypto, page-cache, unsafe, and compression work.

Do not require the advisory pass to be warning-free yet. Current useful warning categories include unchecked integer casts, unnecessary `Result` wrappers, large stack arrays in tests, missing public API error docs, and some avoidable clones. Current noisy categories include style preferences such as `const fn` candidates and long test functions.

Do not enable `clippy::restriction` wholesale. It is a collection of policy lints, not an idiomatic-Rust profile. Cherry-pick restriction lints only when they encode an actual project rule.

## Local Rules

* All normal page reads and writes go through the page cache.
* Passwords are owned and passed as `SecretString`.
* Long-lived secret bytes use `SecretVec` or a more specific secret wrapper.
* Keep `unsafe` blocks tiny, documented, and behind safe wrappers.
* Avoid `unwrap()`/`expect()` in production code unless the invariant is local and explicit.
* Public API changes need direct API tests, not only CLI coverage.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.revault.onepub.dev/docs/rust_development.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.