From ef58c9ee5ecba7f42a6376ea9440294f11f9fe60 Mon Sep 17 00:00:00 2001
From: "F." <fc@hyperd.io>
Date: Thu, 8 Jan 2026 22:57:03 +0100
Subject: [PATCH] docs(readme): add Quick Start; tooling and Docker setup;
 contribution updates

- Replace inline doc paths with Markdown links (usage, security checklist, license)
- Add step-by-step Quick Start (clone, module init via setup-project.sh)
- Document installing core toolchain; optionally enable proto tools via PROTO_ENABLED
- Describe running quality gates and sample app (`make lint`, `make test`, `make run` serving /health on localhost:8000)
- Add Docker/Compose workflow with `.env`, build, and compose instructions
- Summarize high-level Make targets (prepare-toolchain, prepare-proto-tools, init, lint, test/test-race/bench, vet, sec, proto, run, run-container, update-deps/toolchain)
- Normalize Contributing and Code of Conduct sections with links

Docs-only change in README.md.
---
 README.md | 65 +++++++++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 53 insertions(+), 12 deletions(-)

diff --git a/README.md b/README.md
index 818021c..69ef8d2 100644
--- a/README.md
+++ b/README.md
@@ -137,25 +137,66 @@ func main() {
 
 ## Documentation
 
-- Detailed usage and behavior notes: `docs/usage.md`
-- Security checklist: `docs/security-checklist.md`
+- Detailed usage and behavior notes: [Usage](docs/usage.md)
+- A quick reference for teams using sectools in production: [Security checklist](docs/security-checklist.md)
 
 ## Development
 
-```bash
-make test
-make lint
-make sec
-```
+### Quick Start
+
+1. Clone and set your module name
+
+    ```bash
+    git clone https://github.com/hyp3rd/starter.git my-new-project
+    cd my-new-project
+    ./setup-project.sh --module github.com/your/module
+    ```
+
+1. Install toolchain (core). Proto tools stay optional.
+
+    ```bash
+    make prepare-toolchain
+    # If you need proto/gRPC/OpenAPI
+    PROTO_ENABLED=true make prepare-proto-tools
+    ```
+
+1. Run quality gates and sample app
+
+    ```bash
+    make lint
+    make test
+    make run   # serves /health on HOSTNAME:PORT (defaults localhost:8000)
+    ```
+
+1. Optional: Docker and Compose
+
+    ```bash
+    cp .env.example .env   # shared runtime config for compose/requests
+    docker build -t starter-app .
+    docker compose up --build
+    ```
+
+### Make Targets (high level)
+
+- `prepare-toolchain` — install core tools (gci, gofumpt, golangci-lint, staticcheck, govulncheck, gosec)
+- `prepare-proto-tools` — install buf + protoc plugins (optional, controlled by PROTO_ENABLED)
+- `init` — run setup-project.sh with current module and install tooling (respects PROTO_ENABLED)
+- `lint` — gci, gofumpt, staticcheck, golangci-lint
+- `test` / `test-race` / `bench`
+- `vet`, `sec`, `proto`, `run`, `run-container`, `update-deps`, `update-toolchain`
+
+## Contribution Notes
 
-## Contributing
+- Tests required for changes; run `make lint test` before PRs.
+- Suggested branch naming: `feat/<scope>`, `fix/<scope>`, `chore/<scope>`.
+- Update docs when altering tooling, Make targets, or setup steps.
 
-See `CONTRIBUTING.md` for guidelines.
+Follow the [contributing guidelines](./CONTRIBUTING.md).
 
-## Code of Conduct
+### Code of Conduct
 
-See `CODE_OF_CONDUCT.md`.
+Make sure you [observe the Code of Conduct](CODE_OF_CONDUCT.md).
 
 ## License
 
-GPL-3.0. See `LICENSE` for details.
+GPL-3.0. See [LICENSE](./LICENSE) for details.