# Frequently Asked Questions (FAQ)
Everything you need to know about Rivox, answered in plain English.
---
### General & Philosophy
#### 1. Does Rivox replace Cargo, uv, or pnpm?
**No.** Rivox follows the principle **Coordinate. Never Replace.** It delegates 100% of dependency resolution to native ecosystem tools (`cargo`, `uv`, `pnpm`).
#### 2. Does Rivox modify my native lockfiles?
**No.** Native lockfiles (`Cargo.lock`, `uv.lock`, `pnpm-lock.yaml`) remain authoritative. Rivox only reads them to construct a unified multigraph and writes its own metadata lockfile (`rivox.lock`).
#### 3. Is Rivox a dependency resolver?
**No.** Rivox never resolves dependency versions or runs backtracking solver algorithms on its own.
#### 4. Why not just use Bazel or Buck2?
Bazel and Buck2 require rewriting external dependencies into Starlark/BUILD files, creating massive onboarding friction. Rivox works out-of-the-box with standard native manifests (`Cargo.toml`, `pyproject.toml`, `package.json`).
#### 5. Why not use Nix?
Nix requires learning the Nix expression language and rebuilding non-hermetic packages. Rivox lets you keep native developer workflows while providing cross-ecosystem build caching.
#### 6. Is AI involved in build or resolution decisions?
**No.** Constitutional Rule #8 strictly forbids AI from participating in graph resolution, hashing, or build decisions. Rivox is 100% deterministic.
---
### Usage & Compatibility
#### 7. Can I use Rivox in a single-language repository (e.g. Rust only)?
Yes. Rivox can coordinate a single-ecosystem workspace or polyglot monorepos equally well.
#### 8. Does Rivox work on Windows?
Yes. Rivox compiles natively on Windows, macOS, and Linux.
#### 9. Does Rivox require Docker or container runtimes?
No. Rivox is a lightweight, standalone Rust binary with zero container runtime dependencies.
#### 10. How long does it take to add Rivox to an existing repo?
Under 3 minutes. Create a `rivox.toml` manifest at the root and run `rivox build`.
#### 11. Can I run Rivox in offline mode?
Yes. Use `rivox build --offline` to enforce offline native tool operation.
#### 12. What happens if a native tool (like `uv`) is missing?
Rivox detects native prerequisites in `PATH` and fails loudly with clear diagnostic instructions.
---
### Caching & Content-Addressed Storage (CAS)
#### 13. How does Rivox cache work?
Rivox uses Subtree-Based Content-Addressed Storage (CAS) under `~/.rivox/cache/cas`.
#### 14. Will changing a Python dependency invalidate my Rust cache?
**No.** Rivox computes cache keys strictly over transitive package subtrees (RFC-001). Updating Python dependencies does not invalidate Rust build caches.
#### 15. How are directory build outputs (`node_modules`, `.venv`) cached?
Rivox stores Merkleized directory manifest trees (`TreeManifest`) and file blobs using 2-level directory fanout, reconstituting directories via hard-links (RFC-002).
#### 16. Can I clear or prune local cache storage?
Yes. Run `rivox cache prune --days 30` to remove unreferenced CAS artifacts.
#### 17. Does Rivox support REAPI remote caching?
Yes. Rivox includes gRPC REAPI v2 protocol compatibility for `bazel-remote` and Buildbarn integration.
---
### Sandboxing & Security
#### 18. Can I disable sandboxing for debugging?
Yes. Pass `--no-sandbox` during `rivox build`.
#### 19. How does Linux sandboxing work?
On Linux, Rivox isolates build steps using unprivileged user, mount, and network namespaces (`CLONE_NEWNS`, `CLONE_NEWNET`).
#### 20. How does macOS sandboxing work?
On macOS, Rivox generates dynamic Seatbelt (`.sb`) sandbox policies executed via `/usr/bin/sandbox-exec`.
#### 21. Does sandboxing scrub environment variables?
Yes. Sensitive host secrets (`AWS_SECRET_ACCESS_KEY`, `GITHUB_TOKEN`) are scrubbed from sandbox execution contexts.
---
### Supply-Chain Security & Attestation
#### 22. What provenance formats does Rivox generate?
Every `rivox build` emits signed in-toto `.link` statements, SLSA Build Level 2 provenance, and SPDX 2.3 JSON SBOMs into `.rivox/provenance.json`.
#### 23. Are generated SBOMs deterministic?
Yes. SBOM timestamps default to `SOURCE_DATE_EPOCH` / zero-timestamp (`1970-01-01T00:00:00Z`) with RFC 8785 JSON canonicalization (RFC-005).
#### 24. Does Rivox support Sigstore keyless signing?
Yes. Attestation digests are signed via Sigstore OIDC flows and registered with the Rekor transparency log.
---
### CI/CD & Monorepo Scaling
#### 25. How do I use Rivox in GitHub Actions?
Add `rivox build` as your CI build step. See `.github/workflows/ci.yml` for reference configurations.
#### 26. Can I perform a dry-run build in CI?
Yes. Run `rivox build --dry-run` to simulate resolution without modifying files or execution caches.
#### 27. How does `rivox verify` work?
`rivox verify` checks that `rivox.lock` content hashes match live native lockfiles and validates Sigstore provenance signatures.
#### 28. How does Rivox scale on 10,000+ developer monorepos?
By storing file blobs in 2-level fanout directories and deriving keys over subtrees, Rivox scales cleanly to 500,000-node graphs.
#### 29. Can I generate shell completion scripts?
Yes. Run `rivox completions <bash|zsh|fish|powershell|elvish>`.
#### 30. Where can I find deep technical documentation?
Deep architectural specifications, RFCs, and ADRs live in the `docs/` directory.