docs: establish project documentation and licensing

CONTRIBUTING.md

@@ -0,0 +1,167 @@
+# Contributing to VniDrop
+
+Thank you for helping improve VniDrop. Contributions may include bug reports,
+feature proposals, documentation, tests, design feedback, and code.
+
+By participating, you agree to follow the project
+[Code of Conduct](CODE_OF_CONDUCT.md).
+
+## Before You Start
+
+- Search existing issues and pull requests before opening a duplicate.
+- For a substantial feature or architecture change, open an issue first so the
+  approach and platform impact can be discussed.
+- Keep each change focused. Avoid unrelated refactors, dependency upgrades, or
+  repository-wide formatting.
+- Report suspected vulnerabilities through the private process in
+  [`SECURITY.md`](SECURITY.md), never in a public issue with technical details.
+- Never include secrets, private tickets, file contents, key material, or
+  passphrases in an issue, log, test fixture, commit, or pull request.
+
+## Development Setup
+
+Clone the repository and create a branch from an up-to-date `master`:
+
+```bash
+git clone https://github.com/vnidrop/vnidrop.git
+cd vnidrop
+git switch master
+git pull --ff-only
+git switch -c feat/short-description
+```
+
+Use a branch name that describes the outcome, such as
+`feat/folder-share`, `fix/cancel-export-hang`, or `docs/contributing`.
+
+Install the tools needed for the area you plan to change:
+
+- JDK 17 or newer for Gradle and application builds
+- Rust stable with `rustfmt` and Clippy for the transfer core
+- Android SDK and NDK for Android builds
+- Xcode on macOS for iOS builds and simulator tests
+- Node.js 22.12 or newer for the optional diagnostics service
+
+The first Rust and Gradle builds may take several minutes while dependencies are
+downloaded and native components are compiled.
+
+## Repository Structure
+
+| Path | Purpose |
+|------|---------|
+| `crates/vnidrop/` | Rust transfer core, persistence, approval, and streaming |
+| `shared/` | Shared Kotlin Multiplatform UI and platform bridges |
+| `androidApp/` | Android application shell |
+| `iosApp/` | iOS application shell |
+| `desktopApp/` | Desktop JVM application shell |
+| `services/diagnostics-api/` | Optional Cloudflare diagnostics service |
+
+Read the nearest contributor guidance before editing:
+
+- [`AGENTS.md`](AGENTS.md) contains repository-wide engineering rules.
+- [`crates/vnidrop/AGENTS.md`](crates/vnidrop/AGENTS.md) covers the Rust core.
+- [`shared/AGENTS.md`](shared/AGENTS.md) covers Compose and Kotlin
+  Multiplatform work.
+
+## Engineering Expectations
+
+VniDrop follows a few important design constraints:
+
+- File transfer payloads are streamed by Rust and should not be routed through
+  the Kotlin heap as the primary design.
+- Android directory sharing expands SAF trees into individual file descriptors;
+  directory file descriptors are not passed to Rust.
+- Approval and access checks must not be weakened for convenience.
+- Receive publishing must preserve the existing no-overwrite behavior.
+- Locks and synchronous guards must not be held across Rust `.await` points.
+- Bug fixes require a regression test at the lowest layer that demonstrates the
+  failure.
+
+Match the style of nearby code. Comments should explain non-obvious invariants,
+platform constraints, concurrency behavior, or design decisions instead of
+restating the code.
+
+## Testing
+
+Run checks from the repository root. Choose the suite for the files you changed.
+
+### Rust Core
+
+```bash
+cargo fmt --all
+cargo clippy --workspace --all-targets -- -D warnings
+cargo test -p vnidrop
+```
+
+For cancel, export, or output-sink changes, also run:
+
+```bash
+cargo test -p vnidrop --test output_sink
+```
+
+For broader core changes, run the complete workspace suite:
+
+```bash
+cargo test --workspace --all-targets
+```
+
+### Shared Kotlin and Compose
+
+```bash
+./gradlew :shared:jvmTest
+```
+
+Platform-specific checks may also be appropriate:
+
+```bash
+./gradlew :shared:testAndroidHostTest
+./gradlew :shared:iosSimulatorArm64Test
+./gradlew :androidApp:assembleDebug
+```
+
+### Diagnostics Service
+
+```bash
+cd services/diagnostics-api
+npm ci
+npm run check
+```
+
+If a required check cannot run on your machine, explain why in the pull request
+and list the checks you did run.
+
+## Commits
+
+Use concise commit messages that describe the outcome. The repository commonly
+uses Conventional Commit-style subjects:
+
+```text
+feat(core): add folder transfer metadata
+fix(ui): preserve receive progress after rotation
+docs: clarify desktop setup
+```
+
+Create signed commits when your repository configuration requires signing. Do
+not bypass a signing requirement with an unsigned commit.
+
+## Pull Requests
+
+Open pull requests against `master`. A good pull request should:
+
+1. Explain what changed and why.
+2. Stay limited to one coherent outcome.
+3. Link the relevant issue, when one exists.
+4. Describe platform or compatibility implications.
+5. Include regression coverage for bug fixes and behavior changes.
+6. Provide an executable test plan with the exact commands or concrete manual
+   scenarios used for verification.
+7. Avoid generated files, unrelated formatting, and dependency changes unless
+   they are required by the contribution.
+
+Review feedback is part of the collaboration process. Keep follow-up commits
+focused, and resolve review threads only after the concern has been addressed.
+
+## Licensing
+
+VniDrop is distributed under the [Apache License 2.0](LICENSE). Unless explicitly
+stated otherwise, contributions accepted into this repository are distributed
+under the same license.