docs: expand repository docs with roadmap, troubleshooting, contributing and security

CONTRIBUTING.md

@@ -0,0 +1,52 @@
+# Contributing Guide
+
+Thanks for contributing to car64.
+
+## Workflow
+
+- Create a branch from `main`:
+  - `feature/<short-name>` for features
+  - `fix/<short-name>` for bug fixes
+  - `docs/<short-name>` for documentation updates
+- Keep pull requests focused and small when possible.
+- Write clear commit messages (Conventional Commit style is preferred).
+
+## Development Setup
+
+1. Install Flutter stable and run `flutter doctor`.
+2. Copy `.env/flutter_defines.example.json` to `.env/flutter_defines.json`.
+3. Fill in your own Supabase config values.
+4. Run:
+
+```bash
+flutter pub get
+flutter analyze
+```
+
+## Code Style
+
+- Follow existing project style and naming patterns.
+- Prefer small, explicit methods over deeply nested logic.
+- Preserve backend contract names (`hotwheels`, RPC names, etc.) unless migration is intentional.
+
+## Testing & Validation
+
+Before opening a PR:
+
+- Run `flutter analyze`
+- Run available tests
+- Manually test affected flows (scanner, collections, auth, storage upload)
+
+## Pull Request Checklist
+
+- [ ] Scope is clear and focused
+- [ ] Analyzer passes
+- [ ] User-facing strings are intentional and reviewed
+- [ ] No secrets/config values were committed
+- [ ] README/docs updated if behavior changed
+
+## Commit Message Examples
+
+- `fix(scanner): prevent duplicate processing on repeated detections`
+- `perf(collections): coalesce overlapping reload requests`
+- `docs(readme): add release workflow section`

README.md

@@ -10,6 +10,24 @@
 
 ---
 
+## Table of Contents
+
+- [Overview](#overview)
+- [Features](#features)
+- [Tech Stack](#tech-stack)
+- [Prerequisites](#prerequisites)
+- [Configuration](#configuration)
+- [Getting Started](#getting-started)
+- [VS Code Workflows](#vs-code-workflows)
+- [Project Structure (high level)](#project-structure-high-level)
+- [Troubleshooting](#troubleshooting)
+- [Release Checklist](#release-checklist)
+- [Roadmap](#roadmap)
+- [Contributing](#contributing)
+- [Security Notes](#security-notes)
+- [License](#license)
+- [Reference](#reference)
+
 ## Overview
 
 car64 helps collectors scan model IDs, organize personal and shared collections, and keep a clean catalog with community validation/reporting flows.
@@ -116,12 +134,55 @@ Use **Terminal → Run Task**:
 - `lib/utils/` helpers and formatting utilities
 - `lib/theme/` app theme and colors
 
+## Troubleshooting
+
+### App fails at startup with Supabase config error
+
+- Ensure `.env/flutter_defines.json` exists locally.
+- Confirm all required keys are present:
+  - `SUPABASE_URL`
+  - `SUPABASE_ANON_KEY`
+  - `SUPABASE_USE_PKCE`
+
+### Build task works but app cannot connect to backend
+
+- Verify the Supabase URL/key pair belong to the same project.
+- Check Supabase RLS policies and RPC permissions.
+
+### iOS IPA task fails on Windows
+
+- `flutter build ipa` requires macOS + Xcode.
+
+## Release Checklist
+
+- [ ] `flutter pub get`
+- [ ] `flutter analyze`
+- [ ] Manual smoke test on Android
+- [ ] Manual smoke test on iOS
+- [ ] Confirm `.env/flutter_defines.json` points to production Supabase
+- [ ] Build Android `appbundle`
+- [ ] Build iOS `ipa`
+- [ ] Verify auth, scan flow, collections, and upload flows
+
+## Roadmap
+
+- [ ] Optional dark/light theme toggle in settings
+- [ ] Extended scanner confidence hints and retry UX
+- [ ] Bulk actions and better collection analytics
+- [ ] Improved offline behavior for low-connectivity sessions
+
+## Contributing
+
+See `CONTRIBUTING.md` for branching, commit style, and PR guidelines.
+
 ## Security Notes
 
 - Supabase anon keys are intentionally client-side, but RLS and RPC permissions must be strict.
 - Sensitive local config files are git-ignored.
 - User-facing errors are sanitized and shown via global overlays.
 
+For reporting vulnerabilities, see `SECURITY.md`.
+
 ## License
 
 License file is not included in this repository yet.

SECURITY.md

@@ -0,0 +1,31 @@
+# Security Policy
+
+## Supported Versions
+
+This project currently supports the latest active branch in this repository.
+
+## Reporting a Vulnerability
+
+If you discover a security issue, please do not open a public issue with exploit details.
+
+Preferred process:
+
+1. Share a private report with:
+   - A clear description of the issue
+   - Reproduction steps
+   - Impact assessment
+   - Suggested fix (if available)
+2. Allow time for triage and remediation before public disclosure.
+
+## Scope Notes
+
+- Supabase anon keys are client-side by design and are not secret credentials.
+- Real protection depends on strict RLS policies, RPC authorization, and server-side validation.
+- Local config files with runtime values should stay out of version control.
+
+## Recommended Hardening
+
+- Keep Supabase keys in local/CI `dart-define` configuration only.
+- Rotate keys when moving between environments or if misuse is suspected.
+- Audit RLS policies after every schema/function change.
+- Sanitize user-facing error messages (avoid leaking backend internals).