feat: add Voltra CLI apply pipeline for React Native projects

packages/cli/CONTRIBUTING.md

@@ -0,0 +1,47 @@
+# Contributing to `voltra`
+
+This package contains the CLI used to apply Voltra to standard native React Native projects.
+
+For the repo-wide contribution process, see the root [CONTRIBUTING.md](../../CONTRIBUTING.md).
+
+## High-level overview
+
+The CLI is organized around one user-facing workflow: load Voltra config, validate the target native project, apply the requested platform changes, clean up stale generated files, then report the result.
+
+At a high level:
+
+- `src/bin.ts` is the executable entry point.
+- `src/commands/apply.ts` defines the public CLI command and translates argv into apply options.
+- `src/apply/` orchestrates the end-to-end apply pipeline and preflight checks.
+- `src/config/` loads and normalizes Voltra config before any platform work starts.
+- `src/discovery/` resolves the native project layout for Android and iOS.
+- `src/platforms/android/` and `src/platforms/ios/` contain platform-specific preflight and apply logic.
+- `src/state/` tracks Voltra-owned generated files so later runs can clean up stale output safely.
+- `src/reporting/` owns terminal output, errors, and apply summaries.
+- `src/git/` handles git worktree checks before writes begin.
+- `src/fs/` contains shared filesystem helpers used across the pipeline.
+
+## Design intent
+
+The package is intentionally convention-first:
+
+- config loading happens up front
+- discovery and validation fail before writes when the target project is missing or ambiguous
+- platform-specific code owns native mutations
+- only Voltra-owned generated files are tracked for cleanup
+- terminal reporting stays separate from the mutation logic
+
+This separation keeps the apply pipeline straightforward to reason about and makes platform behavior easier to evolve independently.
+
+## Development notes
+
+Useful package-local commands:
+
+```sh
+npm run build --workspace packages/cli
+npm run lint --workspace packages/cli
+npm run typecheck --workspace packages/cli
+npm run test --workspace packages/cli
+```
+
+When changing behavior, prefer keeping orchestration in `src/apply/` and pushing platform-specific details into the relevant platform directory instead of adding cross-platform branching in many places.

packages/cli/README.md

@@ -0,0 +1,43 @@
+![voltra-banner](https://use-voltra.dev/voltra-baner.jpg)
+
+### Voltra CLI for native React Native projects
+
+[![mit licence][license-badge]][license] [![npm downloads][npm-downloads-badge]][npm-downloads] [![PRs Welcome][prs-welcome-badge]][prs-welcome]
+
+`voltra` is the CLI package for applying Voltra to standard native React Native apps.
+
+Use it when you are integrating Voltra into a project that owns its native iOS and Android folders directly, without relying on Expo config plugins to make those changes for you.
+
+For installation and setup instructions, see the Voltra documentation: [use-voltra.dev](https://use-voltra.dev).
+
+## When to use this package
+
+- Native React Native apps that manage `ios/` and `android/` directly.
+- Projects that need Voltra to wire platform-specific files and native project changes outside Expo prebuild.
+
+If you are using Expo config plugins, start with:
+
+- [`@use-voltra/ios-client`](../ios-client)
+- [`@use-voltra/android-client`](../android-client)
+
+## For contributors
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for a high-level overview of the CLI package and its internal structure.
+
+## Authors
+
+Voltra is an open source collaboration between [Saúl Sharma](https://github.com/saulsharma) and [Szymon Chmal](https://github.com/szymonchmal) at [Callstack][callstack-readme-with-love].
+
+If you think it's cool, please star it 🌟. This project will always remain free to use.
+
+[Callstack][callstack-readme-with-love] is a group of React and React Native geeks, contact us at [hello@callstack.com](mailto:hello@callstack.com) if you need any help with these or just want to say hi!
+
+Like the project? ⚛️ [Join the Callstack team](https://callstack.com/careers/?utm_campaign=Senior_RN&utm_source=github&utm_medium=readme) who does amazing stuff for clients and drives React Native Open Source! 🔥
+
+[callstack-readme-with-love]: https://callstack.com/?utm_source=github.com&utm_medium=referral&utm_campaign=voltra&utm_term=readme-with-love
+[license-badge]: https://img.shields.io/npm/l/voltra?style=for-the-badge
+[license]: https://github.com/callstackincubator/voltra/blob/main/LICENSE.txt
+[npm-downloads-badge]: https://img.shields.io/npm/dm/voltra?style=for-the-badge
+[npm-downloads]: https://www.npmjs.com/package/voltra
+[prs-welcome-badge]: https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=for-the-badge
+[prs-welcome]: ./CONTRIBUTING.md