From 12b8336ab24ee282b0c86a5ccb31724b096c197a Mon Sep 17 00:00:00 2001
From: DualFroz <me@dualfroz.com>
Date: Thu, 23 Jul 2026 07:25:52 +0200
Subject: [PATCH] chore: add Cargo.toml OSS metadata and CONTRIBUTING.md
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Cargo.toml had no license/repository/readme/keywords/categories fields
— expected metadata for a public Rust project. Added CONTRIBUTING.md
(build from source, pre-PR checks, code layout) since the repo had no
onboarding doc for contributors beyond the CI gate added earlier this
round; linked from README.
---
 CONTRIBUTING.md | 61 +++++++++++++++++++++++++++++++++++++++++++++++++
 Cargo.toml      |  5 ++++
 README.md       |  5 ++++
 3 files changed, 71 insertions(+)
 create mode 100644 CONTRIBUTING.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..3611c2d
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,61 @@
+# Contributing to vulp
+
+Thanks for looking at vulp. It's a young solo-maintained project, so keep
+that in mind — response times may vary, and larger changes are easier to
+land if discussed in an issue first.
+
+## Building from source
+
+```bash
+git clone https://github.com/dualfroz/fxg.git vulp
+cd vulp
+cargo build --release
+./target/release/vulp --help
+```
+
+Requires a recent stable Rust toolchain (edition 2021). `git2` and `keyring`
+pull in native dependencies (vendored OpenSSL/libgit2, so no system packages
+needed on Linux/macOS/Windows for the build itself).
+
+## Before opening a PR
+
+```bash
+cargo build --all-targets
+cargo clippy --all-targets -- -D warnings
+cargo test
+```
+
+All three run in CI (`.github/workflows/ci.yml`) on every PR — a red check
+means one of them failed. `cargo clippy` must be warning-free; this project
+holds that bar deliberately (see `plan/audit-2026-07-05.md` if you want the
+history of how it got there).
+
+## Code layout
+
+- `hub/` — the TUI's tab-based dashboard (rendering, keymap, modals,
+  background-job spawning). Business logic (`providers/`, `status/`,
+  `config/`, `codeintel/`) is kept separate from rendering (`hub/`,
+  `detail/`, `tui/`) — new features should follow that split rather than
+  mixing API/git calls into render code.
+- `cli_cmds/` — the non-interactive CLI surface (one module per command
+  group). Every CLI command should also be reflected in `docs/cli.md`.
+- `providers/` — one file per git host (`github.rs`, `gitlab.rs`,
+  `gitea.rs`). GitHub is the reference implementation; GitLab/Gitea are
+  intentionally more limited (see `docs/cli.md` and `plan/roadmap.md` for
+  what's a known gap vs. what's missing).
+- Slow operations (API calls, git network ops, shell subprocesses) run on a
+  background `std::thread` and report back over an `mpsc` channel polled
+  once per frame — see any `spawn_*` function in `hub/modals_spawn.rs` for
+  the pattern, including the "don't start a second job on top of a running
+  one" guard those functions check first.
+
+## Reporting bugs / proposing features
+
+Open a GitHub issue. For bugs, a repro (even a rough one) beats a long
+description — this is a TUI, so exact keypresses + terminal emulator matter.
+
+## What this project won't do
+
+No telemetry, no forced update-nagging beyond an informational tile, no
+scope creep into being a general Git GUI — vulp is a workspace-of-many-repos
+tool first.
diff --git a/Cargo.toml b/Cargo.toml
index 98a5f9b..40d4e11 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -4,6 +4,11 @@ version = "0.1.0"
 edition = "2021"
 description = "Multi-repo git workflow manager"
 authors = ["dualfroz"]
+license = "MIT"
+repository = "https://github.com/dualfroz/fxg"
+readme = "README.md"
+keywords = ["git", "tui", "cli", "workflow", "productivity"]
+categories = ["command-line-utilities", "development-tools"]
 build = "build.rs"
 
 [[bin]]
diff --git a/README.md b/README.md
index a82107a..aceab43 100644
--- a/README.md
+++ b/README.md
@@ -122,6 +122,11 @@ kody wyjścia `0` ok · `1` błąd · `2` złe użycie · `3` auth · `4` nie zn
 Listy PR/issues są dziś GitHub-only — na innych providerach zakładki 5/6
 będą puste (known limitation).
 
+## Rozwój / Contributing
+
+Build ze źródeł, wymagania, layout kodu, `cargo clippy`/`cargo test` przed PR:
+patrz [CONTRIBUTING.md](CONTRIBUTING.md).
+
 ## Licencja
 
 MIT — patrz [LICENSE](LICENSE).