feat: Update documentation to clarify Nix usage and enhance onboarding for non-Nix contributors

README.md

@@ -1,6 +1,7 @@
 # FeDIY
 
 FeDIY provides a reproducible Rust development environment using Nix flakes and the fenix toolchain.
+Nix is optional for contributors: if you use it, `nix develop` gives you the exact tools this repository expects without needing to install them globally. If you do not use Nix, you can still work with the standard Rust toolchain.
 
 ## Quick Start
 
@@ -19,11 +20,18 @@ When you enter the devShell (via `direnv allow` or `nix develop`), the following
 
 No manual setup needed! Just start coding.
 
-## Quickstart
+## First Steps
 
 ```sh
 nix develop
 cargo build
+cargo test
+```
+
+If you want a quick overview of what the shell provides, run:
+
+```sh
+nix run .#dev-helper
 ```
 
 ## Flatpak Packaging
@@ -67,6 +75,10 @@ flatpak run com.moturpin.fediy
 | **cargo-edit** | Add/remove/upgrade Cargo dependencies from the CLI |
 | **cargo-watch** | Auto-rebuild on file changes |
 | **flatpak-builder** | Build Flatpak distribution packages |
+| **psql / postgresql** | Local PostgreSQL development and inspection |
+| **gettext** | Localization and translation workflow support |
+| **chromium / playwright** | Browser-based UI and accessibility checks |
+| **podman / podman-compose / buildah** | Linux-only OCI/container tooling |
 | **pre-commit** | Run pre-commit hooks |
 
 ## Testing & Development Features
@@ -141,7 +153,7 @@ See project.toml for example metadata.
 
 ## Helper Tools
 
-- **`nix run .#dev-helper`** - Display tool versions and availability
+- **`nix run .#dev-helper`** - Display tool versions and availability, grouped by task
 - **`cargo build`** - Build the project
 - **`cargo check`** - Quick syntax check without building
 - **`cargo doc --open`** - Generate and view documentation

docs/ARCHITECTURE.md

@@ -21,12 +21,12 @@ Out of scope for early phases:
 
 FeDIY is intended to be shipped and operated through a small set of first-class packaging targets so instance operators can choose the deployment style that fits their environment:
 
-- **Nix flake/devShell**: reproducible development and build environment for contributors and operators who prefer Nix.
+- **Nix flake/devShell**: reproducible development and build environment for contributors and operators who prefer Nix. It is a convenience path, not a requirement for contributing.
 - **Flatpak**: desktop-friendly distribution path for bundled client or companion tooling where applicable.
 - **OCI/Docker container image**: a standard containerized deployment path for managed hosting, Kubernetes, and simple `docker compose` installs.
 - **NixOS module**: optional system integration for operators already using NixOS.
 
-These targets should share the same application artifact and configuration model where possible. Packaging differences should be limited to how the binary is delivered, configured, and run; they should not fork the core runtime behavior.
+These targets should share the same application artifact and configuration model where possible. Packaging differences should be limited to how the binary is delivered, configured, and run; they should not fork the core runtime behavior. Contributors should be able to work productively with standard Rust tooling even if they never enter the Nix shell.
 
 The flake and related packaging shells should be reviewed periodically so the included tools stay aligned with current phase needs. The default posture is to keep the dev environment lean and add tools only when they directly support active work such as building, testing, localization, accessibility validation, container packaging, or release tasks.
 

docs/ROADMAP.md

@@ -10,7 +10,7 @@ Build a federated DIY project-hosting platform in Rust, inspired by the utility
 
 Goals:
 
-- Stabilize development environment and reproducible tooling.
+- Stabilize development environment and reproducible tooling, while keeping the contributor path usable for people who do not use Nix.
 - Define domain language and baseline architecture docs.
 - Establish quality process (TDD/BDD + GitHub Flow).
 - Clarify the core-plus-extension project contract before implementation.
@@ -21,6 +21,7 @@ Exit criteria:
 - Agreed glossary and architecture baseline.
 - Documented contribution and branch workflow.
 - CI skeleton in place for formatting, linting, and tests.
+- Documented onboarding path for non-Nix contributors using standard Rust toolchain commands.
 - ADR for project revision lifecycle (draft/publish/supersede).
 - ADR for composable extension mechanism (shape, namespacing, discovery).
 - ADR for persistence layer architecture (PostgreSQL as primary target; repository abstraction pattern; query library selection; SQLite future-option strategy).

flake.nix

@@ -36,7 +36,7 @@
       templates = {
         default = {
           path = ./.;
-          description = "FeDIY Rust development environment and package outputs for Nix and non-Nix contributors";
+          description = "FeDIY Rust development environment and package outputs; Nix is optional for contributors";
         };
       };
 
@@ -106,8 +106,8 @@
               fi
 
               echo "[FeDIY] Welcome to the dev shell!"
-              echo "If you're new to Nix: this shell gives you the exact tools this repo expects."
+              echo "Nix is optional for contributors. This shell is here if you want a ready-made toolset."
-              echo "Start with 'cargo build'. Use 'nix run .#dev-helper' for a quick tool summary."
+              echo "Start with 'cargo build'. Use 'nix run .#dev-helper' for a quick task summary."
               echo "Tools: cargo, rustc, clippy, rustfmt, rust-analyzer, flatpak-builder, psql, gettext, chromium, playwright"
               echo "Packaging note: the shell is intentionally reviewed and trimmed as the roadmap changes."
               if command -v podman >/dev/null 2>&1; then