sherlock/docs/conventions.md

Conventions

Repository rules that should stay true as the project changes.

Layout

• Shippable binaries live under cmd/<name>/.
• The bootstrap installer lives under setup/; shared install logic lives in internal/installer/.
• Shared Go code lives under internal/. Add no top-level pkg/ until there is an external consumer.
• README.md is a short description plus a docs index.
• VERSION is the release version source of truth.

Go

• Module path: gitea.alexandru.macocian.me/amacocian/sherlock.
• Target Go version: the go directive in go.mod.
• One package main per cmd/<binary>/.
• Non-main packages have a package doc comment in their leading source file.
• New third-party dependencies need a short justification with the change.

Docs

• Keep docs short and functional.
• Prefer links to source files over copied API/tool examples.
• Do not add layout diagrams. Use prose for relationships and source links for details.
• One topic per docs/*.md file; link from README.md.

Naming

• Binaries are kebab-case: gitea-mcp, gssh-mcp, searxng-mcp.
• Agent names match the wrapped CLI: copilot, claude.
• Service names are the config key and wallet key: gitea, grafana, gssh, searxng.

Commits and CI

• Commit style: area: short imperative.
• Keep one logical change per commit.
• .gitea/workflows/release.yaml runs formatting, static analysis, race tests, and build.
• Tags are created from VERSION only after the main-branch release workflow passes.

Security

No secrets in the repository. OAuth tokens live in the OS keyring; config files contain deployment metadata only.