feat(mcp): initial implementation — MCP server, framework indexer, 10 tools, 8 validation rules (v0.1.0)

Introduces code.nochebuena.dev/einherjar/mcp — the Einherjar Model Context Protocol server. A remote, streamable-HTTP service that teaches AI assistants about every other module of the framework: which package exposes which type, what each module guarantees through its compliance tests, the canonical wiring shape for a service, and whether a Go snippet follows the conventions. Indexes the framework on disk at build time and ships a self-contained binary via go:embed; imports nothing from other einherjar/* modules at compile time. server (cmd/server): - Streamable-HTTP MCP server built on github.com/modelcontextprotocol/go-sdk v1.0.0 - mcp.NewServer + mcp.NewStreamableHTTPHandler, served via net/http on EINHERJAR_MCP_ADDR (default :8080) and EINHERJAR_MCP_PATH (default /mcp) - /healthz liveness endpoint; structured JSON logging via log/slog - Loads the embedded data/index.json once at startup; in-memory for the process lifetime indexer (cmd/indexer): - Walks an Einherjar repository checkout (default ../), parses every sibling module's go.mod, README.md, CHANGELOG.md, docs/adr/ADR-*.md, doc.go package comments, every exported type/interface/func/method/const/var (via go/doc on go/parser ASTs), and compliance_test.go - Captures module dependency edges by regex over each go.mod's require lines (einherjar/* paths only; self-reference filtered) - Appends a synthetic "wire" module documenting canonical application wiring conventions, authored at internal/index/builtins/README.md and embedded via go:embed; participates in list_modules / get_module / get_example like a real module internal/index: - Schema einherjar.mcp/index/v1; types: Index, Module, SubPackage, Symbol, ADR, Example, Compliance, InterfaceAssert, ComplianceTest - Build(repoRoot) → *Index walks the repo; BuildBuiltins() returns the synthetic wire module from the embedded markdown - Load([]byte) → *Index validates the schema version on read - FindModule, SearchSymbols helpers used by tools internal/tools (10 tools): - list_modules — enumerate every module with purpose + sub-packages - get_module — package doc, dependencies, sub-packages, key symbols, ADRs, compliance counts; optional embedded README - search_symbols — full-text across name, doc, sub-package, module; filterable by module and kind - get_symbol — full signature, doc comment, source file:line for one symbol - list_adrs — list ADRs across the framework or within one module - get_adr — fetch one ADR's markdown body - get_example — canonical usage snippets extracted from module READMEs and from the synthetic wire conventions - get_compliance — interface assertions (var _ Iface = impl) and structural test names from a module's compliance_test.go - get_changelog — full CHANGELOG.md markdown for one module - validate_snippet — pattern-match a Go snippet against framework conventions internal/rules (8 rules, registered via init() against a single registered slice): - launcher.missing-run — launcher constructed but Run() never called - launcher.no-components — launcher.New() called without any .Append(...) - launcher.run-error-discarded — lc.Run() invoked as an ExprStmt (return ignored) - logz.direct-env-read — os.Getenv("EINHERJAR_LOG_*") bypassing logz config - web.server-not-appended — web/server constructed but not added to the launcher - wire.hook-bad-signature — with<Feature>(...) first param is not launcher.Launcher - wire.hook-outside-beforestart — repo/service/handler construction or route registration at the top level of a hook (outside lc.BeforeStart) - wire.route-specific-after-param — /users/{id} registered before a sibling /users/me of the same length and method (chi would shadow the literal route) Synthetic wire module (internal/index/builtins/README.md): - Project layout (cmd/<app>/main.go + internal/wire/*.go + per-feature domain dirs) - Canonical Run() shape: config → logger → infra (db, cache, pool, mc, srv) → cross- cutting (validator, permission provider) → launcher.New → lc.Append(infra...) → withMigrations / withSuperAdminSeed / withHealth / withFeature hooks → return lc.Run() - Canonical with<Feature> hook shape: signature (launcher.Launcher first, server.Server second, deps last), single lc.BeforeStart closure containing all construction + route registration - chi route ordering, srv.With(authz(...)) authorization, middleware helpers (authz / skipPublicPaths / skipMethodPath), tokenSignerAdapter pattern showing that the framework exposes Signer.Sign as a primitive and the application owns the access/refresh response shape Packaging: - Multi-stage Dockerfile that builds from the einherjar repository root (docker build -f mcp/Dockerfile .) so cmd/indexer can walk every sibling module at image-build time; runtime layer is gcr.io/distroless/static-debian12:nonroot - 86-byte placeholder data/index.json committed once with `git add -f`; subsequent indexer runs overwrite it locally but the file is .gitignored - .gitea/CODEOWNERS and pull_request_template.md mirror the sibling layout Design notes: - mcp depends on nothing in einherjar/* — it reads the framework via the filesystem at index time. This keeps mcp outside the framework dependency graph and lets it index any version of einherjar without versioning itself in lock-step. - All structured-output tool responses initialise empty slices ([]Type{}) rather than relying on Go's nil-marshals-to-null default, so the SDK's JSON-schema output validator never rejects a tools/call result.
2026-05-29 18:12:45 +00:00
commit cc62906c6f
33 changed files with 3560 additions and 0 deletions
--- a/internal/index/builder.go
+++ b/internal/index/builder.go
@@ -0,0 +1,415 @@
+package index
+
+import (
+	"bytes"
+	"fmt"
+	"go/ast"
+	"go/doc"
+	"go/parser"
+	"go/printer"
+	"go/token"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strings"
+	"time"
+)
+
+// Build walks the Einherjar repository rooted at repoRoot, indexes every
+// sibling module (any immediate subdirectory containing a go.mod), and
+// returns an Index ready to be written to disk.
+//
+// The mcp module itself is skipped to avoid self-reference.
+func Build(repoRoot string) (*Index, error) {
+	idx := &Index{
+		Schema:    SchemaVersion,
+		Framework: "einherjar",
+		BuiltAt:   time.Now().UTC(),
+	}
+	entries, err := os.ReadDir(repoRoot)
+	if err != nil {
+		return nil, fmt.Errorf("read repo root: %w", err)
+	}
+	for _, e := range entries {
+		if !e.IsDir() {
+			continue
+		}
+		name := e.Name()
+		if strings.HasPrefix(name, ".") || name == "mcp" || name == "vendor" {
+			continue
+		}
+		modDir := filepath.Join(repoRoot, name)
+		if _, err := os.Stat(filepath.Join(modDir, "go.mod")); err != nil {
+			continue
+		}
+		mod, err := buildModule(modDir, name)
+		if err != nil {
+			return nil, fmt.Errorf("module %s: %w", name, err)
+		}
+		idx.Modules = append(idx.Modules, *mod)
+	}
+	return idx, nil
+}
+
+func buildModule(modDir, name string) (*Module, error) {
+	m := &Module{
+		Name:      name,
+		DependsOn: []string{},
+		Compliance: Compliance{
+			InterfaceAsserts: []InterfaceAssert{},
+			Tests:            []ComplianceTest{},
+		},
+	}
+
+	if data, err := os.ReadFile(filepath.Join(modDir, "go.mod")); err == nil {
+		m.ImportPath = parseModulePath(data)
+		m.GoVersion = parseGoVersion(data)
+		m.DependsOn = parseDependsOn(data, name)
+	}
+	if data, err := os.ReadFile(filepath.Join(modDir, "README.md")); err == nil {
+		m.Readme = string(data)
+		m.Purpose = extractPurpose(string(data))
+		m.Examples = extractExamples(name, string(data))
+	}
+	if data, err := os.ReadFile(filepath.Join(modDir, "CHANGELOG.md")); err == nil {
+		m.Changelog = string(data)
+	}
+	m.Compliance = parseCompliance(name, modDir)
+
+	adrDir := filepath.Join(modDir, "docs", "adr")
+	if adrs, err := os.ReadDir(adrDir); err == nil {
+		for _, a := range adrs {
+			if a.IsDir() || !strings.HasPrefix(a.Name(), "ADR-") || !strings.HasSuffix(a.Name(), ".md") {
+				continue
+			}
+			body, err := os.ReadFile(filepath.Join(adrDir, a.Name()))
+			if err != nil {
+				continue
+			}
+			id, title := parseADRHeader(a.Name(), body)
+			m.ADRs = append(m.ADRs, ADR{Module: name, ID: id, Title: title, Body: string(body)})
+		}
+	}
+
+	if err := indexPackages(modDir, m); err != nil {
+		return nil, err
+	}
+	return m, nil
+}
+
+func indexPackages(modDir string, m *Module) error {
+	return filepath.WalkDir(modDir, func(path string, d fs.DirEntry, err error) error {
+		if err != nil {
+			return nil
+		}
+		if !d.IsDir() {
+			return nil
+		}
+		base := d.Name()
+		if base != filepath.Base(modDir) && (strings.HasPrefix(base, ".") || base == "vendor" || base == "testdata" || base == "docs") {
+			return filepath.SkipDir
+		}
+
+		fset := token.NewFileSet()
+		pkgs, err := parser.ParseDir(fset, path, func(fi os.FileInfo) bool {
+			return !strings.HasSuffix(fi.Name(), "_test.go")
+		}, parser.ParseComments)
+		if err != nil || len(pkgs) == 0 {
+			return nil
+		}
+		rel, _ := filepath.Rel(modDir, path)
+		if rel == "." {
+			rel = ""
+		}
+		for pkgName, pkg := range pkgs {
+			if pkgName == "main" {
+				continue
+			}
+			subName := pkgName
+			if rel == "" {
+				subName = ""
+			}
+			docPkg := doc.New(pkg, "./", doc.AllDecls)
+			if rel == "" && m.Doc == "" && docPkg.Doc != "" {
+				m.Doc = strings.TrimSpace(docPkg.Doc)
+			}
+			if rel != "" || docPkg.Doc != "" {
+				m.SubPackages = append(m.SubPackages, SubPackage{
+					Name:       subName,
+					ImportPath: joinImport(m.ImportPath, rel),
+					Doc:        strings.TrimSpace(docPkg.Doc),
+				})
+			}
+			collectSymbols(m, subName, modDir, fset, docPkg)
+		}
+		return nil
+	})
+}
+
+func collectSymbols(m *Module, sub, modDir string, fset *token.FileSet, p *doc.Package) {
+	for _, t := range p.Types {
+		kind := "type"
+		if isInterface(t.Decl) {
+			kind = "interface"
+		}
+		m.Symbols = append(m.Symbols, newSymbol(m.Name, sub, kind, t.Name, t.Doc, t.Decl, fset, modDir))
+		for _, f := range t.Funcs {
+			m.Symbols = append(m.Symbols, newSymbol(m.Name, sub, "func", f.Name, f.Doc, f.Decl, fset, modDir))
+		}
+		for _, f := range t.Methods {
+			m.Symbols = append(m.Symbols, newSymbol(m.Name, sub, "method", t.Name+"."+f.Name, f.Doc, f.Decl, fset, modDir))
+		}
+	}
+	for _, f := range p.Funcs {
+		m.Symbols = append(m.Symbols, newSymbol(m.Name, sub, "func", f.Name, f.Doc, f.Decl, fset, modDir))
+	}
+	for _, v := range p.Consts {
+		for _, name := range v.Names {
+			m.Symbols = append(m.Symbols, newSymbol(m.Name, sub, "const", name, v.Doc, v.Decl, fset, modDir))
+		}
+	}
+	for _, v := range p.Vars {
+		for _, name := range v.Names {
+			m.Symbols = append(m.Symbols, newSymbol(m.Name, sub, "var", name, v.Doc, v.Decl, fset, modDir))
+		}
+	}
+}
+
+func newSymbol(mod, sub, kind, name, docStr string, decl ast.Node, fset *token.FileSet, modDir string) Symbol {
+	pos := fset.Position(decl.Pos())
+	rel, _ := filepath.Rel(modDir, pos.Filename)
+	return Symbol{
+		Module:     mod,
+		SubPackage: sub,
+		Kind:       kind,
+		Name:       name,
+		Signature:  formatNode(fset, decl),
+		Doc:        strings.TrimSpace(docStr),
+		File:       rel,
+		Line:       pos.Line,
+	}
+}
+
+func formatNode(fset *token.FileSet, node ast.Node) string {
+	var buf bytes.Buffer
+	cfg := printer.Config{Mode: printer.UseSpaces, Tabwidth: 4}
+	if err := cfg.Fprint(&buf, fset, node); err != nil {
+		return ""
+	}
+	s := buf.String()
+	if i := strings.Index(s, "{"); i > 0 && (strings.HasPrefix(s, "func") || strings.HasPrefix(s, "type")) {
+		return strings.TrimSpace(s[:i])
+	}
+	return strings.TrimSpace(s)
+}
+
+func isInterface(decl *ast.GenDecl) bool {
+	if decl == nil {
+		return false
+	}
+	for _, spec := range decl.Specs {
+		ts, ok := spec.(*ast.TypeSpec)
+		if !ok {
+			continue
+		}
+		if _, ok := ts.Type.(*ast.InterfaceType); ok {
+			return true
+		}
+	}
+	return false
+}
+
+var (
+	modulePathRe   = regexp.MustCompile(`(?m)^module\s+(\S+)`)
+	goVersionRe    = regexp.MustCompile(`(?m)^go\s+(\S+)`)
+	adrNameRe      = regexp.MustCompile(`^(ADR-\d+)-(.+)\.md$`)
+	h1Re           = regexp.MustCompile(`(?m)^#\s+(.+)$`)
+	fenceRe        = regexp.MustCompile("(?s)```([a-zA-Z0-9_+\\-]*)\\n(.*?)```")
+	einherjarDepRe = regexp.MustCompile(`code\.nochebuena\.dev/einherjar/([a-zA-Z0-9_-]+)`)
+)
+
+func parseModulePath(data []byte) string {
+	if m := modulePathRe.FindSubmatch(data); m != nil {
+		return string(m[1])
+	}
+	return ""
+}
+
+func parseGoVersion(data []byte) string {
+	if m := goVersionRe.FindSubmatch(data); m != nil {
+		return string(m[1])
+	}
+	return ""
+}
+
+// parseDependsOn extracts the set of einherjar modules referenced by go.mod's
+// require/replace lines. The module's own name is filtered out so a module
+// never lists itself as a dependency.
+func parseDependsOn(data []byte, self string) []string {
+	seen := map[string]bool{}
+	for _, m := range einherjarDepRe.FindAllSubmatch(data, -1) {
+		name := string(m[1])
+		if name == self {
+			continue
+		}
+		seen[name] = true
+	}
+	out := make([]string, 0, len(seen))
+	for k := range seen {
+		out = append(out, k)
+	}
+	sort.Strings(out)
+	return out
+}
+
+// parseCompliance parses compliance_test.go (when present) and returns its
+// interface assertions and test functions. Missing or unparseable files yield
+// an empty Compliance, not an error — the file is optional.
+func parseCompliance(modName, modDir string) Compliance {
+	c := Compliance{
+		InterfaceAsserts: []InterfaceAssert{},
+		Tests:            []ComplianceTest{},
+	}
+	path := filepath.Join(modDir, "compliance_test.go")
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return c
+	}
+	fset := token.NewFileSet()
+	file, err := parser.ParseFile(fset, path, data, parser.ParseComments)
+	if err != nil {
+		return c
+	}
+	rel, _ := filepath.Rel(modDir, path)
+
+	for _, decl := range file.Decls {
+		switch d := decl.(type) {
+		case *ast.GenDecl:
+			if d.Tok != token.VAR {
+				continue
+			}
+			for _, spec := range d.Specs {
+				vs, ok := spec.(*ast.ValueSpec)
+				if !ok {
+					continue
+				}
+				if len(vs.Names) != 1 || vs.Names[0].Name != "_" {
+					continue
+				}
+				if vs.Type == nil || len(vs.Values) == 0 {
+					continue
+				}
+				c.InterfaceAsserts = append(c.InterfaceAsserts, InterfaceAssert{
+					Module:    modName,
+					Interface: formatNode(fset, vs.Type),
+					Impl:      formatNode(fset, vs.Values[0]),
+					File:      rel,
+					Line:      fset.Position(vs.Pos()).Line,
+				})
+			}
+		case *ast.FuncDecl:
+			if d.Recv != nil {
+				continue
+			}
+			if !strings.HasPrefix(d.Name.Name, "Test") {
+				continue
+			}
+			testDoc := ""
+			if d.Doc != nil {
+				testDoc = strings.TrimSpace(d.Doc.Text())
+			}
+			c.Tests = append(c.Tests, ComplianceTest{
+				Module: modName,
+				Name:   d.Name.Name,
+				Doc:    testDoc,
+				File:   rel,
+				Line:   fset.Position(d.Pos()).Line,
+			})
+		}
+	}
+	return c
+}
+
+func parseADRHeader(filename string, body []byte) (id, title string) {
+	if m := adrNameRe.FindStringSubmatch(filename); m != nil {
+		id = m[1]
+		title = strings.ReplaceAll(m[2], "-", " ")
+	}
+	if m := h1Re.FindSubmatch(body); m != nil {
+		title = strings.TrimSpace(string(m[1]))
+	}
+	return id, title
+}
+
+// extractPurpose returns the first non-empty, non-heading, non-badge paragraph
+// from the README — typically the blockquote tagline or opening sentence.
+func extractPurpose(readme string) string {
+	for _, line := range strings.Split(readme, "\n") {
+		t := strings.TrimSpace(line)
+		if t == "" || strings.HasPrefix(t, "#") || strings.HasPrefix(t, "[!") || strings.HasPrefix(t, "[![") {
+			continue
+		}
+		t = strings.TrimPrefix(t, "> ")
+		t = strings.TrimPrefix(t, ">")
+		if t == "" {
+			continue
+		}
+		return t
+	}
+	return ""
+}
+
+// extractExamples lifts fenced code blocks from a README, attaching them to
+// the most recent H2/H3 heading as the example title and the best-guess
+// sub-package (the heading lowercased, matched against known sub-packages
+// later — or left blank).
+func extractExamples(module, readme string) []Example {
+	var out []Example
+	lines := strings.Split(readme, "\n")
+	currentHeading := ""
+	for _, l := range lines {
+		t := strings.TrimSpace(l)
+		if strings.HasPrefix(t, "## ") || strings.HasPrefix(t, "### ") {
+			currentHeading = strings.TrimSpace(strings.TrimLeft(t, "# "))
+		}
+	}
+	_ = currentHeading // headings are walked again below to correlate blocks
+
+	matches := fenceRe.FindAllStringSubmatchIndex(readme, -1)
+	for _, m := range matches {
+		lang := readme[m[2]:m[3]]
+		code := readme[m[4]:m[5]]
+		title := nearestHeading(readme, m[0])
+		out = append(out, Example{
+			Module:   module,
+			Title:    title,
+			Code:     strings.TrimSpace(code),
+			Language: lang,
+		})
+	}
+	return out
+}
+
+func nearestHeading(readme string, before int) string {
+	prefix := readme[:before]
+	lines := strings.Split(prefix, "\n")
+	for i := len(lines) - 1; i >= 0; i-- {
+		t := strings.TrimSpace(lines[i])
+		if strings.HasPrefix(t, "## ") || strings.HasPrefix(t, "### ") {
+			return strings.TrimSpace(strings.TrimLeft(t, "# "))
+		}
+	}
+	return ""
+}
+
+func joinImport(base, rel string) string {
+	if base == "" {
+		return ""
+	}
+	if rel == "" || rel == "." {
+		return base
+	}
+	return base + "/" + filepath.ToSlash(rel)
+}
--- a/internal/index/builtins.go
+++ b/internal/index/builtins.go
@@ -0,0 +1,35 @@
+package index
+
+import (
+	_ "embed"
+)
+
+//go:embed builtins/README.md
+var builtinsReadme string
+
+// BuildBuiltins returns the synthetic "wire" module that documents canonical
+// Einherjar application wiring conventions. The content is authored as
+// markdown in builtins/README.md and embedded at compile time.
+//
+// The returned module participates in list_modules, get_module, and
+// get_example exactly like a real Einherjar module — applications can ask
+// the MCP server for "wire" knowledge the same way they ask for "core" or
+// "web" knowledge.
+func BuildBuiltins() Module {
+	m := Module{
+		Name:        "wire",
+		ImportPath:  "(application internal/wire)",
+		Purpose:     extractPurpose(builtinsReadme),
+		Readme:      builtinsReadme,
+		DependsOn:   []string{},
+		SubPackages: []SubPackage{},
+		Symbols:     []Symbol{},
+		ADRs:        []ADR{},
+		Compliance: Compliance{
+			InterfaceAsserts: []InterfaceAssert{},
+			Tests:            []ComplianceTest{},
+		},
+	}
+	m.Examples = extractExamples("wire", builtinsReadme)
+	return m
+}
--- a/internal/index/builtins/README.md
+++ b/internal/index/builtins/README.md
@@ -0,0 +1,338 @@
+# Wiring Conventions
+
+> Forging a service is mostly wiring. Do it the same way every time.
+
+This is not an Einherjar *module* — it is the canonical *application* shape
+that uses Einherjar modules. Apps live in their own repository with an
+`internal/wire/` package that mirrors this template. The conventions here are
+distilled from a production service that has shipped on the predecessor
+micro-libs (`code.nochebuena.dev/go/*`) and have been re-mapped to the
+einherjar import paths.
+
+## Project layout
+
+```
+cmd/<app>/main.go              one-line entrypoint that calls wire.Run()
+internal/wire/launcher.go      Run() — builds infra and registers feature hooks
+internal/wire/<feature>.go     one file per feature, hosts a with<Feature> hook
+internal/wire/middleware.go    authz, skipPublicPaths, skipMethodPath helpers
+internal/wire/migrations.go    withMigrations hook
+internal/wire/seed.go          withSuperAdminSeed and other startup seeds
+internal/<feature>/dto/        request/response DTOs
+internal/<feature>/handler/    HTTP handlers
+internal/<feature>/repository/ data access
+internal/<feature>/service/    domain logic
+```
+
+`cmd/<app>/main.go` must contain nothing but the call to `wire.Run()` and an
+`os.Exit(1)` on error. Everything else lives in `internal/wire/`.
+
+## Run
+
+The application entry point. The order below is load-bearing: configuration
+first, observability second, infrastructure third, cross-cutting helpers
+fourth, then the launcher with every component appended, then feature hooks,
+then `lc.Run()`.
+
+```go
+package wire
+
+import (
+	"strings"
+
+	"github.com/google/uuid"
+
+	authjwt "code.nochebuena.dev/einherjar/auth-jwt"
+	"code.nochebuena.dev/einherjar/auth/authmw"
+	"code.nochebuena.dev/einherjar/auth/rbac"
+	"code.nochebuena.dev/einherjar/cache-valkey"
+	"code.nochebuena.dev/einherjar/core/launcher"
+	"code.nochebuena.dev/einherjar/core/logz"
+	"code.nochebuena.dev/einherjar/core/valid"
+	"code.nochebuena.dev/einherjar/db-postgres"
+	"code.nochebuena.dev/einherjar/storage-minio"
+	"code.nochebuena.dev/einherjar/web/mw"
+	"code.nochebuena.dev/einherjar/web/server"
+	"code.nochebuena.dev/einherjar/worker"
+
+	"myapp/internal/config"
+)
+
+func Run() error {
+	cfg, err := config.Load()
+	if err != nil {
+		return err
+	}
+
+	logger := logz.New(logz.Config{
+		JSON:       !strings.EqualFold(cfg.AppEnv, "local"),
+		StaticArgs: []any{"service", "myapp", "env", cfg.AppEnv},
+	})
+
+	signer := authjwt.NewHMACSigner([]byte(cfg.JWT.Secret))
+
+	publicPaths := []string{
+		"/health",
+		"/api/v1/auth/login",
+		"/api/v1/auth/refresh",
+	}
+
+	db    := postgres.New(logger, cfg.PG)
+	cache := valkey.New(logger, cfg.VK)
+	pool  := worker.New(logger, cfg.Worker)
+	mc    := minio.New(logger, cfg.MinIO)
+	srv   := server.New(logger, cfg.Server,
+		server.WithMiddleware(
+			mw.RequestID(uuid.NewString),
+			mw.Recover(logger),
+			mw.CORS(cfg.CORSOrigins),
+			mw.RequestLogger(logger),
+			authjwt.AuthMiddleware(logger, signer, publicPaths),
+			authmw.EnrichmentMiddleware(logger, &claimsEnricher{}),
+		),
+	)
+
+	v        := valid.New(valid.WithMessageProvider(valid.SpanishMessages))
+	provider := rbac.NewClaimsPermissionProvider("masks", claimsFromCtx)
+
+	lc := launcher.New(logger)
+	lc.Append(db, cache, pool, mc, srv)
+
+	withMigrations(lc, logger, cfg)
+	withSuperAdminSeed(lc, db, logger, cfg)
+
+	withHealth(lc, srv, logger, db, cache, mc)
+	withUsers(lc, srv, db, logger, provider, v)
+	// … one withFeature(...) call per feature in your domain.
+
+	return lc.Run()
+}
+```
+
+## Feature hook
+
+One file per feature in `internal/wire/`. The function signature is fixed:
+`launcher.Launcher` first, `server.Server` second when registering routes,
+deps last. The body is *one* call to `lc.BeforeStart`. Everything else —
+repository construction, service construction, handler construction, route
+registration — lives inside the closure.
+
+```go
+package wire
+
+import (
+	"code.nochebuena.dev/einherjar/contracts/security"
+	"code.nochebuena.dev/einherjar/core/launcher"
+	"code.nochebuena.dev/einherjar/core/logz"
+	"code.nochebuena.dev/einherjar/core/valid"
+	"code.nochebuena.dev/einherjar/db-postgres"
+	"code.nochebuena.dev/einherjar/web/server"
+
+	"myapp/internal/domains"
+	userhandler "myapp/internal/user/handler"
+	userrepo    "myapp/internal/user/repository"
+	usersvc     "myapp/internal/user/service"
+)
+
+func withUsers(
+	lc       launcher.Launcher,
+	srv      server.Server,
+	db       postgres.Component,
+	logger   logz.Logger,
+	provider security.PermissionProvider,
+	v        valid.Validator,
+) {
+	lc.BeforeStart(func() error {
+		repo := userrepo.New(db)
+		uow  := postgres.NewUnitOfWork(logger, db)
+		svc  := usersvc.New(repo, uow)
+		h    := userhandler.New(svc, v)
+
+		// Literal-segment routes register BEFORE parametrised siblings.
+		// chi matches the first registered route that fits; if /users/{id}
+		// came first, "me" would bind to {id} and /users/me/password would
+		// never be reached.
+		srv.Put("/api/v1/users/me/password", h.ChangeOwnPassword)
+
+		srv.With(authz(provider, domains.ResourceUsers, domains.GrantReadUser)).
+			Get("/api/v1/users", h.ListUsers)
+		srv.With(authz(provider, domains.ResourceUsers, domains.GrantCreateUser)).
+			Post("/api/v1/users", h.CreateUser)
+		srv.With(authz(provider, domains.ResourceUsers, domains.GrantUpdateUser)).
+			Put("/api/v1/users/{user_id}", h.UpdateUser)
+		srv.With(authz(provider, domains.ResourceUsers, domains.GrantDeleteUser)).
+			Delete("/api/v1/users/{user_id}", h.DeleteUser)
+
+		return nil
+	})
+}
+```
+
+## Route ordering
+
+chi matches paths in registration order. Always register literal-segment
+routes before parametrised-segment routes that share the same prefix.
+
+✅ Correct:
+
+```go
+srv.Put("/api/v1/users/me/password", h.ChangeOwnPassword)
+srv.Put("/api/v1/users/{user_id}",   h.UpdateUser)
+```
+
+❌ Wrong — chi binds `me` to `{user_id}` and the literal route is unreachable:
+
+```go
+srv.Put("/api/v1/users/{user_id}",   h.UpdateUser)
+srv.Put("/api/v1/users/me/password", h.ChangeOwnPassword)
+```
+
+## Authorization
+
+Every protected route registers with `.With(authz(provider, resource, grant))`:
+
+```go
+srv.With(authz(provider, domains.ResourceUsers, domains.GrantReadUser)).
+    Get("/api/v1/users", h.ListUsers)
+```
+
+Resource constants and grant bits live in `internal/domains/`. Routes that
+the caller owns (`/me/...`) intentionally skip authz — they are reachable to
+any authenticated user.
+
+## Middleware helpers
+
+These belong in `internal/wire/middleware.go` and are used across every
+feature hook.
+
+```go
+// authz returns a per-route authorization middleware that checks one bit.
+func authz(p security.PermissionProvider, resource string, bit int) func(http.Handler) http.Handler {
+	return authmw.AuthzMiddleware(nil, p, resource, security.Permission(bit))
+}
+
+// skipPublicPaths wraps mw so it is bypassed for any path that matches publicPaths.
+// Use this for middleware that must not run on unauthenticated endpoints
+// (e.g. EnrichmentMiddleware).
+func skipPublicPaths(publicPaths []string, mw func(http.Handler) http.Handler) func(http.Handler) http.Handler {
+	return func(next http.Handler) http.Handler {
+		inner := mw(next)
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			for _, p := range publicPaths {
+				if matched, _ := path.Match(p, r.URL.Path); matched {
+					next.ServeHTTP(w, r)
+					return
+				}
+			}
+			inner.ServeHTTP(w, r)
+		})
+	}
+}
+
+// skipMethodPath bypasses mw only when BOTH method and path match. Use this
+// to expose ONE method on an otherwise-authenticated path (e.g. GET
+// /api/v1/config public while PUT is not). Adding such a path to
+// publicPaths would silently strip identity from context on the protected
+// methods, breaking authz().
+func skipMethodPath(method, pathPattern string, mw func(http.Handler) http.Handler) func(http.Handler) http.Handler {
+	return func(next http.Handler) http.Handler {
+		inner := mw(next)
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			if r.Method == method {
+				if matched, _ := path.Match(pathPattern, r.URL.Path); matched {
+					next.ServeHTTP(w, r)
+					return
+				}
+			}
+			inner.ServeHTTP(w, r)
+		})
+	}
+}
+```
+
+## Adapters at the wire boundary
+
+When a framework type does not match a service-layer port, write a small
+typed adapter in `internal/wire/`. Always compile-time assert with
+`var _ TargetIface = (*adapter)(nil)`.
+
+The framework intentionally exposes only `Signer.Sign(claims) (string, error)`
+— **the framework gives you a signing primitive; the access/refresh strategy,
+claim layout, and response shape are application concerns.** A "helper" that
+returned a fixed `{access, refresh, type, expiresIn}` struct would silently
+decide for every app whether refresh tokens exist, what fields to expose,
+and what casing to use. Those are wire-format choices the app owns.
+
+```go
+import (
+	"time"
+
+	"github.com/golang-jwt/jwt/v5"
+	"github.com/google/uuid"
+
+	authjwt "code.nochebuena.dev/einherjar/auth-jwt"
+)
+
+type tokenSignerAdapter struct {
+	signer authjwt.Signer
+	cfg    authjwt.TokenConfig
+}
+
+var _ authsvc.TokenSigner = (*tokenSignerAdapter)(nil)
+
+func (a *tokenSignerAdapter) IssueTokenPair(subject string, custom map[string]any) (authdto.TokenPairResponse, error) {
+	now := time.Now()
+
+	access := jwt.MapClaims{
+		"sub": subject,
+		"iss": a.cfg.Issuer,
+		"iat": now.Unix(),
+		"exp": now.Add(a.cfg.AccessTTL).Unix(),
+	}
+	for k, v := range custom {
+		access[k] = v
+	}
+	accessToken, err := a.signer.Sign(access)
+	if err != nil {
+		return authdto.TokenPairResponse{}, err
+	}
+
+	refreshToken, err := a.signer.Sign(jwt.MapClaims{
+		"sub": subject,
+		"jti": uuid.NewString(),
+		"iat": now.Unix(),
+		"exp": now.Add(a.cfg.RefreshTTL).Unix(),
+	})
+	if err != nil {
+		return authdto.TokenPairResponse{}, err
+	}
+
+	return authdto.TokenPairResponse{
+		AccessToken:  accessToken,
+		RefreshToken: refreshToken,
+		TokenType:    "Bearer",
+		ExpiresIn:    int(a.cfg.AccessTTL.Seconds()),
+	}, nil
+}
+```
+
+## Migrations and seeds
+
+Migrations and seeds register as `BeforeStart` hooks too. They run after all
+components have initialised but before any of them have started, so the
+database is reachable and the server is not yet accepting traffic.
+
+```go
+func withMigrations(lc launcher.Launcher, logger logz.Logger, cfg config.Config) {
+	lc.BeforeStart(func() error {
+		if err := migrations.RunMigrations(context.Background(), logger, cfg); err != nil {
+			logger.Error("migrations: failed to apply", err)
+			return err
+		}
+		return nil
+	})
+}
+```
+
+Seeds must be **idempotent**: count first, only mutate when needed, log the
+skip when nothing was done.
--- a/internal/index/index.go
+++ b/internal/index/index.go
@@ -0,0 +1,164 @@
+// Package index defines the on-disk schema of the Einherjar framework index
+// and provides a loader for the embedded JSON blob.
+//
+// The index is built once at deploy time by cmd/indexer and consumed by every
+// MCP tool. Keeping it small, denormalised, and JSON-shaped means tools can
+// be implemented as straightforward in-memory filters.
+package index
+
+import (
+	"encoding/json"
+	"fmt"
+	"strings"
+	"time"
+)
+
+// SchemaVersion identifies the on-disk index format. Bump when fields change
+// in a way that breaks older consumers.
+const SchemaVersion = "einherjar.mcp/index/v1"
+
+// Index is the root of the embedded framework knowledge.
+type Index struct {
+	Schema    string    `json:"schema"`
+	Framework string    `json:"framework"`
+	BuiltAt   time.Time `json:"builtAt"`
+	Modules   []Module  `json:"modules"`
+}
+
+// Module describes one Einherjar module (e.g. core, web, auth-jwt).
+type Module struct {
+	Name        string       `json:"name"`
+	ImportPath  string       `json:"importPath"`
+	Purpose     string       `json:"purpose"`
+	Doc         string       `json:"doc,omitempty"`
+	GoVersion   string       `json:"goVersion"`
+	DependsOn   []string     `json:"dependsOn"`
+	SubPackages []SubPackage `json:"subPackages"`
+	Symbols     []Symbol     `json:"symbols"`
+	ADRs        []ADR        `json:"adrs"`
+	Examples    []Example    `json:"examples"`
+	Compliance  Compliance   `json:"compliance"`
+	Readme      string       `json:"readme,omitempty"`
+	Changelog   string       `json:"changelog,omitempty"`
+}
+
+// Compliance captures a module's compliance_test.go contents: compile-time
+// interface assertions and the names of structural tests. It exists so an AI
+// assistant can know about machine-checked conventions before it writes code
+// that would violate them.
+type Compliance struct {
+	InterfaceAsserts []InterfaceAssert `json:"interfaceAsserts"`
+	Tests            []ComplianceTest  `json:"tests"`
+}
+
+// InterfaceAssert mirrors one `var _ Iface = impl` line in compliance_test.go.
+type InterfaceAssert struct {
+	Module    string `json:"module"`
+	Interface string `json:"interface"`
+	Impl      string `json:"impl"`
+	File      string `json:"file"`
+	Line      int    `json:"line"`
+}
+
+// ComplianceTest mirrors one Test* function in compliance_test.go.
+type ComplianceTest struct {
+	Module string `json:"module"`
+	Name   string `json:"name"`
+	Doc    string `json:"doc"`
+	File   string `json:"file"`
+	Line   int    `json:"line"`
+}
+
+// SubPackage is one importable sub-package of a module.
+type SubPackage struct {
+	Name       string `json:"name"`
+	ImportPath string `json:"importPath"`
+	Doc        string `json:"doc"`
+}
+
+// Symbol is one exported declaration (type, func, interface, const, var).
+type Symbol struct {
+	Module     string `json:"module"`
+	SubPackage string `json:"subPackage"`
+	Kind       string `json:"kind"`
+	Name       string `json:"name"`
+	Signature  string `json:"signature"`
+	Doc        string `json:"doc"`
+	File       string `json:"file"`
+	Line       int    `json:"line"`
+}
+
+// ADR is one architectural decision record.
+type ADR struct {
+	Module string `json:"module"`
+	ID     string `json:"id"`
+	Title  string `json:"title"`
+	Body   string `json:"body"`
+}
+
+// Example is a fenced code block lifted from a module README.
+type Example struct {
+	Module     string `json:"module"`
+	SubPackage string `json:"subPackage"`
+	Title      string `json:"title"`
+	Code       string `json:"code"`
+	Language   string `json:"language"`
+}
+
+// Load parses the embedded JSON blob into an Index. It validates the schema
+// version and returns an empty (but non-nil) Index when the blob is the
+// placeholder shipped before the indexer has been run.
+func Load(raw []byte) (*Index, error) {
+	if len(raw) == 0 {
+		return &Index{Schema: SchemaVersion, Framework: "einherjar"}, nil
+	}
+	idx := &Index{}
+	if err := json.Unmarshal(raw, idx); err != nil {
+		return nil, fmt.Errorf("index: parse: %w", err)
+	}
+	if idx.Schema != "" && idx.Schema != SchemaVersion {
+		return nil, fmt.Errorf("index: schema mismatch: got %q want %q", idx.Schema, SchemaVersion)
+	}
+	return idx, nil
+}
+
+// FindModule returns the module with the given name, or nil if absent.
+func (i *Index) FindModule(name string) *Module {
+	for k := range i.Modules {
+		if i.Modules[k].Name == name {
+			return &i.Modules[k]
+		}
+	}
+	return nil
+}
+
+// SearchSymbols returns up to limit symbols whose name or doc contains q
+// (case-insensitive). Module name and sub-package are also searched.
+func (i *Index) SearchSymbols(q string, limit int) []Symbol {
+	if limit <= 0 {
+		limit = 25
+	}
+	needle := strings.ToLower(q)
+	out := make([]Symbol, 0, limit)
+	for _, m := range i.Modules {
+		for _, s := range m.Symbols {
+			if matches(s, needle) {
+				out = append(out, s)
+				if len(out) >= limit {
+					return out
+				}
+			}
+		}
+	}
+	return out
+}
+
+func matches(s Symbol, needle string) bool {
+	if needle == "" {
+		return true
+	}
+	return strings.Contains(strings.ToLower(s.Name), needle) ||
+		strings.Contains(strings.ToLower(s.Doc), needle) ||
+		strings.Contains(strings.ToLower(s.SubPackage), needle) ||
+		strings.Contains(strings.ToLower(s.Module), needle)
+}
--- a/internal/rules/rules.go
+++ b/internal/rules/rules.go
@@ -0,0 +1,286 @@
+// Package rules defines the lightweight, pattern-based conventions enforced
+// by the validate_snippet MCP tool.
+//
+// These are not a substitute for "go vet" or running the user's tests. They
+// catch wiring mistakes that an AI assistant frequently makes when first
+// adopting Einherjar: forgetting to call Run(), constructing a Launcher
+// without registering components, reading EINHERJAR_* env vars directly
+// instead of letting the framework load them, and so on.
+package rules
+
+import (
+	"fmt"
+	"go/ast"
+	"go/parser"
+	"go/token"
+	"strings"
+)
+
+// Severity describes how seriously a finding should be treated.
+type Severity string
+
+const (
+	SeverityError   Severity = "error"
+	SeverityWarning Severity = "warning"
+	SeverityInfo    Severity = "info"
+)
+
+// Finding is one rule hit against a snippet.
+type Finding struct {
+	RuleID   string   `json:"ruleId"`
+	Severity Severity `json:"severity"`
+	Module   string   `json:"module,omitempty"`
+	Message  string   `json:"message"`
+	Hint     string   `json:"hint,omitempty"`
+	Line     int      `json:"line,omitempty"`
+}
+
+// Rule is a single named convention check.
+type Rule struct {
+	ID       string
+	Severity Severity
+	Module   string
+	Check    func(ctx *Context) []Finding
+}
+
+// Context is the parsed view of a snippet provided to every rule.
+type Context struct {
+	Fset    *token.FileSet
+	File    *ast.File
+	Imports map[string]string   // path → local name (e.g. "code.nochebuena.dev/einherjar/core/launcher" → "launcher")
+	Calls   []CallSite          // every function call in the file
+}
+
+// CallSite is a recorded function call. Func is the textual form
+// ("launcher.New", "lc.Append", "lc.Run").
+type CallSite struct {
+	Func string
+	Line int
+}
+
+// Run parses the source and applies every rule, returning all findings in
+// order. If the source cannot be parsed even after wrapping in a synthetic
+// package, parse errors are returned as findings with rule id "parse".
+func Run(src string) []Finding {
+	fset := token.NewFileSet()
+	file, err := parser.ParseFile(fset, "snippet.go", src, parser.AllErrors|parser.ParseComments)
+	if err != nil {
+		wrapped := "package _snippet\n\nfunc _main() {\n" + src + "\n}\n"
+		fset = token.NewFileSet()
+		file, err = parser.ParseFile(fset, "snippet.go", wrapped, parser.AllErrors|parser.ParseComments)
+		if err != nil {
+			return []Finding{{
+				RuleID:   "parse",
+				Severity: SeverityError,
+				Message:  "could not parse snippet: " + err.Error(),
+			}}
+		}
+	}
+
+	ctx := &Context{Fset: fset, File: file, Imports: map[string]string{}}
+	for _, imp := range file.Imports {
+		path := strings.Trim(imp.Path.Value, `"`)
+		name := guessImportName(path)
+		if imp.Name != nil && imp.Name.Name != "" && imp.Name.Name != "_" {
+			name = imp.Name.Name
+		}
+		ctx.Imports[path] = name
+	}
+
+	ast.Inspect(file, func(n ast.Node) bool {
+		call, ok := n.(*ast.CallExpr)
+		if !ok {
+			return true
+		}
+		name := exprName(call.Fun)
+		if name == "" {
+			return true
+		}
+		ctx.Calls = append(ctx.Calls, CallSite{Func: name, Line: fset.Position(call.Pos()).Line})
+		return true
+	})
+
+	var findings []Finding
+	for _, r := range registered {
+		for _, f := range r.Check(ctx) {
+			f.RuleID = r.ID
+			if f.Severity == "" {
+				f.Severity = r.Severity
+			}
+			if f.Module == "" {
+				f.Module = r.Module
+			}
+			findings = append(findings, f)
+		}
+	}
+	return findings
+}
+
+func guessImportName(path string) string {
+	i := strings.LastIndex(path, "/")
+	if i < 0 {
+		return path
+	}
+	return path[i+1:]
+}
+
+func exprName(e ast.Expr) string {
+	switch v := e.(type) {
+	case *ast.Ident:
+		return v.Name
+	case *ast.SelectorExpr:
+		return exprName(v.X) + "." + v.Sel.Name
+	}
+	return ""
+}
+
+// Importing reports whether the snippet imports a path with the given suffix
+// (e.g. "core/launcher" matches "code.nochebuena.dev/einherjar/core/launcher").
+func (c *Context) Importing(suffix string) bool {
+	for path := range c.Imports {
+		if strings.HasSuffix(path, suffix) {
+			return true
+		}
+	}
+	return false
+}
+
+// Calls reports whether any call site has a textual form ending in suffix.
+// For example, suffix ".Run" matches "lc.Run" and "launcher.Run" alike.
+func (c *Context) Called(suffix string) bool {
+	for _, cs := range c.Calls {
+		if strings.HasSuffix(cs.Func, suffix) {
+			return true
+		}
+	}
+	return false
+}
+
+// registered is the static rule catalog. Add new conventions here.
+var registered = []Rule{
+	{
+		ID:       "launcher.missing-run",
+		Severity: SeverityError,
+		Module:   "core",
+		Check: func(c *Context) []Finding {
+			if !c.Importing("einherjar/core/launcher") {
+				return nil
+			}
+			if !c.Called("launcher.New") && !c.Called(".New") {
+				return nil
+			}
+			if c.Called(".Run") {
+				return nil
+			}
+			return []Finding{{
+				Message: "core/launcher constructed but Run() never called — application will never start",
+				Hint:    "After lc := launcher.New(logger); lc.Append(...); call if err := lc.Run(); err != nil { ... }",
+			}}
+		},
+	},
+	{
+		ID:       "launcher.no-components",
+		Severity: SeverityWarning,
+		Module:   "core",
+		Check: func(c *Context) []Finding {
+			if !c.Importing("einherjar/core/launcher") {
+				return nil
+			}
+			if c.Called("launcher.New") && !c.Called(".Append") {
+				return []Finding{{
+					Message: "Launcher created but no components appended — Run() will start an empty application",
+					Hint:    "Use lc.Append(db, cache, server) before lc.Run() to register lifecycle components",
+				}}
+			}
+			return nil
+		},
+	},
+	{
+		ID:       "logz.direct-env-read",
+		Severity: SeverityWarning,
+		Module:   "core",
+		Check: func(c *Context) []Finding {
+			if !c.Importing("einherjar/core/logz") {
+				return nil
+			}
+			var hits []Finding
+			ast.Inspect(c.File, func(n ast.Node) bool {
+				call, ok := n.(*ast.CallExpr)
+				if !ok {
+					return true
+				}
+				if exprName(call.Fun) != "os.Getenv" || len(call.Args) == 0 {
+					return true
+				}
+				lit, ok := call.Args[0].(*ast.BasicLit)
+				if !ok {
+					return true
+				}
+				if strings.HasPrefix(strings.Trim(lit.Value, `"`), "EINHERJAR_LOG_") {
+					hits = append(hits, Finding{
+						Message: fmt.Sprintf("reading %s directly via os.Getenv bypasses logz configuration", strings.Trim(lit.Value, `"`)),
+						Hint:    "logz.New reads EINHERJAR_LOG_* automatically; pass logz.Config and let the framework load it",
+						Line:    c.Fset.Position(call.Pos()).Line,
+					})
+				}
+				return true
+			})
+			return hits
+		},
+	},
+	{
+		ID:       "launcher.run-error-discarded",
+		Severity: SeverityWarning,
+		Module:   "core",
+		Check: func(c *Context) []Finding {
+			if !c.Importing("einherjar/core/launcher") || !c.Called(".Run") {
+				return nil
+			}
+			discarded := false
+			ast.Inspect(c.File, func(n ast.Node) bool {
+				expr, ok := n.(*ast.ExprStmt)
+				if !ok {
+					return true
+				}
+				call, ok := expr.X.(*ast.CallExpr)
+				if !ok {
+					return true
+				}
+				if strings.HasSuffix(exprName(call.Fun), ".Run") {
+					discarded = true
+				}
+				return true
+			})
+			if !discarded {
+				return nil
+			}
+			return []Finding{{
+				Message: "Launcher.Run() return value discarded — startup failures will go unnoticed",
+				Hint:    "Capture the error: if err := lc.Run(); err != nil { logger.Error(...); os.Exit(1) }",
+			}}
+		},
+	},
+	{
+		ID:       "web.server-not-appended",
+		Severity: SeverityWarning,
+		Module:   "web",
+		Check: func(c *Context) []Finding {
+			if !c.Importing("einherjar/web/server") || !c.Importing("einherjar/core/launcher") {
+				return nil
+			}
+			if !c.Called(".Append") {
+				return nil
+			}
+			// Heuristic: warn if server.New is constructed but not appended via .Append.
+			// We can't statically prove the argument was the server, so this is informational.
+			if c.Called("server.New") {
+				return []Finding{{
+					Severity: SeverityInfo,
+					Message:  "web/server is constructed — ensure it is passed to launcher.Append() so its lifecycle is managed",
+					Hint:     "lc.Append(srv) lets the launcher start and gracefully stop the HTTP server",
+				}}
+			}
+			return nil
+		},
+	},
+}
--- a/internal/rules/wire_rules.go
+++ b/internal/rules/wire_rules.go
@@ -0,0 +1,233 @@
+package rules
+
+import (
+	"fmt"
+	"go/ast"
+	"go/token"
+	"strings"
+)
+
+func init() {
+	registered = append(registered,
+		Rule{
+			ID:       "wire.hook-bad-signature",
+			Severity: SeverityWarning,
+			Module:   "wire",
+			Check:    checkHookSignature,
+		},
+		Rule{
+			ID:       "wire.hook-outside-beforestart",
+			Severity: SeverityWarning,
+			Module:   "wire",
+			Check:    checkHookBodyShape,
+		},
+		Rule{
+			ID:       "wire.route-specific-after-param",
+			Severity: SeverityWarning,
+			Module:   "web",
+			Check:    checkRouteOrdering,
+		},
+	)
+}
+
+// isHookName reports whether name matches the with<Feature> convention.
+// A hook is "with" + capital letter + anything, so "with" and "withers"
+// don't qualify but "withUsers", "withAuth", "withSuperAdminSeed" do.
+func isHookName(name string) bool {
+	if len(name) < 5 || !strings.HasPrefix(name, "with") {
+		return false
+	}
+	c := name[4]
+	return c >= 'A' && c <= 'Z'
+}
+
+func checkHookSignature(c *Context) []Finding {
+	var findings []Finding
+	for _, decl := range c.File.Decls {
+		fn, ok := decl.(*ast.FuncDecl)
+		if !ok || fn.Recv != nil || !isHookName(fn.Name.Name) {
+			continue
+		}
+		params := fn.Type.Params
+		if params == nil || len(params.List) == 0 {
+			findings = append(findings, Finding{
+				Message: fmt.Sprintf("hook %s has no parameters; expected first param launcher.Launcher", fn.Name.Name),
+				Hint:    "func with<Feature>(lc launcher.Launcher, srv server.Server, deps...)",
+				Line:    c.Fset.Position(fn.Pos()).Line,
+			})
+			continue
+		}
+		first := exprName(params.List[0].Type)
+		if !strings.Contains(first, "Launcher") {
+			findings = append(findings, Finding{
+				Message: fmt.Sprintf("hook %s first param is %q; expected launcher.Launcher", fn.Name.Name, first),
+				Hint:    "Always pass the launcher as the first argument so the hook can register BeforeStart.",
+				Line:    c.Fset.Position(fn.Pos()).Line,
+			})
+		}
+	}
+	return findings
+}
+
+func checkHookBodyShape(c *Context) []Finding {
+	var findings []Finding
+	for _, decl := range c.File.Decls {
+		fn, ok := decl.(*ast.FuncDecl)
+		if !ok || fn.Recv != nil || fn.Body == nil || !isHookName(fn.Name.Name) {
+			continue
+		}
+		for _, stmt := range fn.Body.List {
+			if !suspiciousTopLevelStmt(stmt) {
+				continue
+			}
+			findings = append(findings, Finding{
+				Message: fmt.Sprintf("hook %s performs wiring outside lc.BeforeStart", fn.Name.Name),
+				Hint:    "Move repo/service/handler construction and route registration inside lc.BeforeStart(func() error { ... return nil }).",
+				Line:    c.Fset.Position(stmt.Pos()).Line,
+			})
+		}
+	}
+	return findings
+}
+
+// suspiciousTopLevelStmt is true for top-level statements inside a hook that
+// look like wiring work (route registration or component construction) but
+// are not the canonical lc.BeforeStart or lc.Append calls.
+func suspiciousTopLevelStmt(stmt ast.Stmt) bool {
+	if expr, ok := stmt.(*ast.ExprStmt); ok {
+		if call, ok := expr.X.(*ast.CallExpr); ok {
+			name := exprName(call.Fun)
+			if strings.HasSuffix(name, ".BeforeStart") ||
+				strings.HasSuffix(name, ".Append") ||
+				strings.HasSuffix(name, ".Run") {
+				return false
+			}
+		}
+	}
+	suspicious := false
+	ast.Inspect(stmt, func(n ast.Node) bool {
+		call, ok := n.(*ast.CallExpr)
+		if !ok {
+			return true
+		}
+		name := exprName(call.Fun)
+		switch {
+		case strings.HasSuffix(name, ".Get"),
+			strings.HasSuffix(name, ".Post"),
+			strings.HasSuffix(name, ".Put"),
+			strings.HasSuffix(name, ".Patch"),
+			strings.HasSuffix(name, ".Delete"),
+			strings.HasSuffix(name, ".New"):
+			suspicious = true
+			return false
+		}
+		return true
+	})
+	return suspicious
+}
+
+type routeReg struct {
+	method string
+	path   string
+	pos    token.Pos
+}
+
+func collectRoutes(file *ast.File) []routeReg {
+	var routes []routeReg
+	ast.Inspect(file, func(n ast.Node) bool {
+		call, ok := n.(*ast.CallExpr)
+		if !ok {
+			return true
+		}
+		sel, ok := call.Fun.(*ast.SelectorExpr)
+		if !ok {
+			return true
+		}
+		switch sel.Sel.Name {
+		case "Get", "Post", "Put", "Patch", "Delete":
+		default:
+			return true
+		}
+		if len(call.Args) < 1 {
+			return true
+		}
+		lit, ok := call.Args[0].(*ast.BasicLit)
+		if !ok || lit.Kind != token.STRING {
+			return true
+		}
+		routes = append(routes, routeReg{
+			method: sel.Sel.Name,
+			path:   strings.Trim(lit.Value, `"`),
+			pos:    call.Pos(),
+		})
+		return true
+	})
+	return routes
+}
+
+func checkRouteOrdering(c *Context) []Finding {
+	routes := collectRoutes(c.File)
+	var findings []Finding
+	for i := 0; i < len(routes); i++ {
+		for j := i + 1; j < len(routes); j++ {
+			if routes[i].method != routes[j].method {
+				continue
+			}
+			if !routesConflict(routes[i].path, routes[j].path) {
+				continue
+			}
+			findings = append(findings, Finding{
+				Message: fmt.Sprintf("%s %s registered before %s %s — chi will bind %q to a path parameter and the literal route becomes unreachable",
+					routes[i].method, routes[i].path,
+					routes[j].method, routes[j].path,
+					conflictingSegment(routes[i].path, routes[j].path),
+				),
+				Hint: "Register literal-segment routes before parametrised siblings that share the same prefix.",
+				Line: c.Fset.Position(routes[i].pos).Line,
+			})
+		}
+	}
+	return findings
+}
+
+// routesConflict reports whether `param` is a parametrised route that would
+// shadow `literal` (a route differing only in one segment being a literal
+// where param has {placeholder}).
+func routesConflict(param, literal string) bool {
+	p := strings.Split(strings.Trim(param, "/"), "/")
+	l := strings.Split(strings.Trim(literal, "/"), "/")
+	if len(p) != len(l) {
+		return false
+	}
+	hasParam := false
+	for i := range p {
+		pIsParam := isParamSeg(p[i])
+		lIsParam := isParamSeg(l[i])
+		if pIsParam {
+			if lIsParam {
+				return false
+			}
+			hasParam = true
+			continue
+		}
+		if p[i] != l[i] {
+			return false
+		}
+	}
+	return hasParam
+}
+
+func isParamSeg(s string) bool {
+	return strings.HasPrefix(s, "{") && strings.HasSuffix(s, "}")
+}
+
+func conflictingSegment(param, literal string) string {
+	p := strings.Split(strings.Trim(param, "/"), "/")
+	l := strings.Split(strings.Trim(literal, "/"), "/")
+	for i := range p {
+		if isParamSeg(p[i]) && !isParamSeg(l[i]) {
+			return l[i]
+		}
+	}
+	return ""
+}
--- a/internal/tools/get_adr.go
+++ b/internal/tools/get_adr.go
@@ -0,0 +1,40 @@
+package tools
+
+import (
+	"context"
+	"strings"
+
+	"code.nochebuena.dev/einherjar/mcp/internal/index"
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+)
+
+type getADRInput struct {
+	Module string `json:"module" jsonschema:"the module name owning the ADR, e.g. core"`
+	ID     string `json:"id" jsonschema:"the ADR identifier, e.g. ADR-001"`
+}
+
+type getADROutput struct {
+	Module string `json:"module"`
+	ID     string `json:"id"`
+	Title  string `json:"title"`
+	Body   string `json:"body"`
+}
+
+func registerGetADR(s *mcp.Server, idx *index.Index) {
+	mcp.AddTool(s, &mcp.Tool{
+		Name:        "get_adr",
+		Description: "Fetch the full markdown body of one architectural decision record by module and ID.",
+	}, func(ctx context.Context, req *mcp.CallToolRequest, args getADRInput) (*mcp.CallToolResult, getADROutput, error) {
+		m := idx.FindModule(args.Module)
+		if m == nil {
+			return errorResult("module not found: " + args.Module), getADROutput{}, nil
+		}
+		for _, a := range m.ADRs {
+			if strings.EqualFold(a.ID, args.ID) {
+				out := getADROutput{Module: m.Name, ID: a.ID, Title: a.Title, Body: a.Body}
+				return jsonText(out), out, nil
+			}
+		}
+		return errorResult("ADR not found: " + args.ID + " in module " + args.Module), getADROutput{}, nil
+	})
+}
--- a/internal/tools/get_changelog.go
+++ b/internal/tools/get_changelog.go
@@ -0,0 +1,31 @@
+package tools
+
+import (
+	"context"
+
+	"code.nochebuena.dev/einherjar/mcp/internal/index"
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+)
+
+type getChangelogInput struct {
+	Module string `json:"module" jsonschema:"the module name, e.g. core"`
+}
+
+type getChangelogOutput struct {
+	Module    string `json:"module"`
+	Changelog string `json:"changelog"`
+}
+
+func registerGetChangelog(s *mcp.Server, idx *index.Index) {
+	mcp.AddTool(s, &mcp.Tool{
+		Name:        "get_changelog",
+		Description: "Return the CHANGELOG.md markdown for one Einherjar module. Use to learn what changed in recent releases and to advise on upgrade-relevant differences.",
+	}, func(ctx context.Context, req *mcp.CallToolRequest, args getChangelogInput) (*mcp.CallToolResult, getChangelogOutput, error) {
+		m := idx.FindModule(args.Module)
+		if m == nil {
+			return errorResult("module not found: " + args.Module), getChangelogOutput{}, nil
+		}
+		out := getChangelogOutput{Module: m.Name, Changelog: m.Changelog}
+		return jsonText(out), out, nil
+	})
+}
--- a/internal/tools/get_compliance.go
+++ b/internal/tools/get_compliance.go
@@ -0,0 +1,44 @@
+package tools
+
+import (
+	"context"
+
+	"code.nochebuena.dev/einherjar/mcp/internal/index"
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+)
+
+type getComplianceInput struct {
+	Module string `json:"module" jsonschema:"the module name, e.g. core"`
+}
+
+type getComplianceOutput struct {
+	Module           string                  `json:"module"`
+	InterfaceAsserts []index.InterfaceAssert `json:"interfaceAsserts"`
+	Tests            []index.ComplianceTest  `json:"tests"`
+}
+
+func registerGetCompliance(s *mcp.Server, idx *index.Index) {
+	mcp.AddTool(s, &mcp.Tool{
+		Name:        "get_compliance",
+		Description: "Return a module's machine-checked conventions from compliance_test.go: every `var _ Iface = impl` interface assertion (the contracts the module promises to satisfy) and every Test* function (the structural rules the module enforces on itself). Use this before writing or reviewing code in a module to learn which conventions are actively guarded.",
+	}, func(ctx context.Context, req *mcp.CallToolRequest, args getComplianceInput) (*mcp.CallToolResult, getComplianceOutput, error) {
+		m := idx.FindModule(args.Module)
+		if m == nil {
+			return errorResult("module not found: " + args.Module), getComplianceOutput{}, nil
+		}
+		asserts := m.Compliance.InterfaceAsserts
+		if asserts == nil {
+			asserts = []index.InterfaceAssert{}
+		}
+		tests := m.Compliance.Tests
+		if tests == nil {
+			tests = []index.ComplianceTest{}
+		}
+		out := getComplianceOutput{
+			Module:           m.Name,
+			InterfaceAsserts: asserts,
+			Tests:            tests,
+		}
+		return jsonText(out), out, nil
+	})
+}
--- a/internal/tools/get_example.go
+++ b/internal/tools/get_example.go
@@ -0,0 +1,39 @@
+package tools
+
+import (
+	"context"
+	"strings"
+
+	"code.nochebuena.dev/einherjar/mcp/internal/index"
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+)
+
+type getExampleInput struct {
+	Module string `json:"module" jsonschema:"the module name, e.g. core"`
+	Topic  string `json:"topic,omitempty" jsonschema:"optional substring matched against the example title (case-insensitive)"`
+}
+
+type getExampleOutput struct {
+	Examples []index.Example `json:"examples"`
+}
+
+func registerGetExample(s *mcp.Server, idx *index.Index) {
+	mcp.AddTool(s, &mcp.Tool{
+		Name:        "get_example",
+		Description: "Return canonical usage examples for a module, extracted from its README. Filter by topic substring (e.g. 'Logger', 'Launcher') to narrow the result.",
+	}, func(ctx context.Context, req *mcp.CallToolRequest, args getExampleInput) (*mcp.CallToolResult, getExampleOutput, error) {
+		m := idx.FindModule(args.Module)
+		if m == nil {
+			return errorResult("module not found: " + args.Module), getExampleOutput{}, nil
+		}
+		needle := strings.ToLower(args.Topic)
+		out := getExampleOutput{Examples: []index.Example{}}
+		for _, ex := range m.Examples {
+			if needle != "" && !strings.Contains(strings.ToLower(ex.Title), needle) {
+				continue
+			}
+			out.Examples = append(out.Examples, ex)
+		}
+		return jsonText(out), out, nil
+	})
+}
--- a/internal/tools/get_module.go
+++ b/internal/tools/get_module.go
@@ -0,0 +1,103 @@
+package tools
+
+import (
+	"context"
+
+	"code.nochebuena.dev/einherjar/mcp/internal/index"
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+)
+
+type getModuleInput struct {
+	Name          string `json:"name" jsonschema:"the module name, e.g. core, web, auth-jwt"`
+	IncludeReadme bool   `json:"includeReadme,omitempty" jsonschema:"when true, embed the full README markdown in the response"`
+}
+
+type getModuleOutput struct {
+	Name        string             `json:"name"`
+	ImportPath  string             `json:"importPath"`
+	Purpose     string             `json:"purpose"`
+	Doc         string             `json:"doc"`
+	GoVersion   string             `json:"goVersion"`
+	DependsOn   []string           `json:"dependsOn"`
+	SubPackages []index.SubPackage `json:"subPackages"`
+	KeySymbols  []symbolHeader     `json:"keySymbols"`
+	ADRs        []adrHeader        `json:"adrs"`
+	Compliance  complianceSummary  `json:"compliance"`
+	Readme      string             `json:"readme,omitempty"`
+}
+
+type complianceSummary struct {
+	InterfaceAssertCount int `json:"interfaceAssertCount"`
+	TestCount            int `json:"testCount"`
+}
+
+type symbolHeader struct {
+	Kind       string `json:"kind"`
+	Name       string `json:"name"`
+	SubPackage string `json:"subPackage"`
+	Signature  string `json:"signature"`
+}
+
+type adrHeader struct {
+	ID    string `json:"id"`
+	Title string `json:"title"`
+}
+
+func registerGetModule(s *mcp.Server, idx *index.Index) {
+	mcp.AddTool(s, &mcp.Tool{
+		Name:        "get_module",
+		Description: "Describe one Einherjar module: sub-packages, key exported symbols (types/interfaces/funcs), and ADRs. Set includeReadme=true to also receive the README markdown.",
+	}, func(ctx context.Context, req *mcp.CallToolRequest, args getModuleInput) (*mcp.CallToolResult, getModuleOutput, error) {
+		m := idx.FindModule(args.Name)
+		if m == nil {
+			return errorResult("module not found: " + args.Name), getModuleOutput{}, nil
+		}
+
+		key := make([]symbolHeader, 0, len(m.Symbols))
+		for _, sym := range m.Symbols {
+			if sym.Kind == "type" || sym.Kind == "interface" || sym.Kind == "func" {
+				key = append(key, symbolHeader{
+					Kind: sym.Kind, Name: sym.Name, SubPackage: sym.SubPackage, Signature: sym.Signature,
+				})
+			}
+		}
+
+		adrs := make([]adrHeader, 0, len(m.ADRs))
+		for _, a := range m.ADRs {
+			adrs = append(adrs, adrHeader{ID: a.ID, Title: a.Title})
+		}
+
+		subs := make([]index.SubPackage, 0, len(m.SubPackages))
+		for _, sp := range m.SubPackages {
+			if sp.Name == "" {
+				continue
+			}
+			subs = append(subs, sp)
+		}
+
+		deps := m.DependsOn
+		if deps == nil {
+			deps = []string{}
+		}
+
+		out := getModuleOutput{
+			Name:        m.Name,
+			ImportPath:  m.ImportPath,
+			Purpose:     m.Purpose,
+			Doc:         m.Doc,
+			GoVersion:   m.GoVersion,
+			DependsOn:   deps,
+			SubPackages: subs,
+			KeySymbols:  key,
+			ADRs:        adrs,
+			Compliance: complianceSummary{
+				InterfaceAssertCount: len(m.Compliance.InterfaceAsserts),
+				TestCount:            len(m.Compliance.Tests),
+			},
+		}
+		if args.IncludeReadme {
+			out.Readme = m.Readme
+		}
+		return jsonText(out), out, nil
+	})
+}
--- a/internal/tools/get_symbol.go
+++ b/internal/tools/get_symbol.go
@@ -0,0 +1,42 @@
+package tools
+
+import (
+	"context"
+	"strings"
+
+	"code.nochebuena.dev/einherjar/mcp/internal/index"
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+)
+
+type getSymbolInput struct {
+	Module     string `json:"module" jsonschema:"the module name, e.g. core"`
+	Name       string `json:"name" jsonschema:"the symbol name; for methods use Type.Method"`
+	SubPackage string `json:"subPackage,omitempty" jsonschema:"narrow to a specific sub-package, e.g. launcher"`
+}
+
+type getSymbolOutput struct {
+	Matches []index.Symbol `json:"matches"`
+}
+
+func registerGetSymbol(s *mcp.Server, idx *index.Index) {
+	mcp.AddTool(s, &mcp.Tool{
+		Name:        "get_symbol",
+		Description: "Fetch full signature, doc comment, and source location for one symbol. Returns every match across sub-packages — use the subPackage filter when ambiguous.",
+	}, func(ctx context.Context, req *mcp.CallToolRequest, args getSymbolInput) (*mcp.CallToolResult, getSymbolOutput, error) {
+		m := idx.FindModule(args.Module)
+		if m == nil {
+			return errorResult("module not found: " + args.Module), getSymbolOutput{}, nil
+		}
+		out := getSymbolOutput{Matches: []index.Symbol{}}
+		for _, sym := range m.Symbols {
+			if !strings.EqualFold(sym.Name, args.Name) {
+				continue
+			}
+			if args.SubPackage != "" && sym.SubPackage != args.SubPackage {
+				continue
+			}
+			out.Matches = append(out.Matches, sym)
+		}
+		return jsonText(out), out, nil
+	})
+}
--- a/internal/tools/list_adrs.go
+++ b/internal/tools/list_adrs.go
@@ -0,0 +1,40 @@
+package tools
+
+import (
+	"context"
+
+	"code.nochebuena.dev/einherjar/mcp/internal/index"
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+)
+
+type listADRsInput struct {
+	Module string `json:"module,omitempty" jsonschema:"restrict to one module by name"`
+}
+
+type listADRsOutput struct {
+	ADRs []adrSummary `json:"adrs"`
+}
+
+type adrSummary struct {
+	Module string `json:"module"`
+	ID     string `json:"id"`
+	Title  string `json:"title"`
+}
+
+func registerListADRs(s *mcp.Server, idx *index.Index) {
+	mcp.AddTool(s, &mcp.Tool{
+		Name:        "list_adrs",
+		Description: "List architectural decision records across Einherjar. Optionally restrict to one module. Use to discover the rationale behind framework design choices.",
+	}, func(ctx context.Context, req *mcp.CallToolRequest, args listADRsInput) (*mcp.CallToolResult, listADRsOutput, error) {
+		out := listADRsOutput{ADRs: []adrSummary{}}
+		for _, m := range idx.Modules {
+			if args.Module != "" && m.Name != args.Module {
+				continue
+			}
+			for _, a := range m.ADRs {
+				out.ADRs = append(out.ADRs, adrSummary{Module: m.Name, ID: a.ID, Title: a.Title})
+			}
+		}
+		return jsonText(out), out, nil
+	})
+}
--- a/internal/tools/list_modules.go
+++ b/internal/tools/list_modules.go
@@ -0,0 +1,47 @@
+package tools
+
+import (
+	"context"
+
+	"code.nochebuena.dev/einherjar/mcp/internal/index"
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+)
+
+type listModulesInput struct{}
+
+type moduleSummary struct {
+	Name        string   `json:"name"`
+	ImportPath  string   `json:"importPath"`
+	Purpose     string   `json:"purpose"`
+	GoVersion   string   `json:"goVersion"`
+	SubPackages []string `json:"subPackages"`
+}
+
+type listModulesOutput struct {
+	Modules []moduleSummary `json:"modules"`
+}
+
+func registerListModules(s *mcp.Server, idx *index.Index) {
+	mcp.AddTool(s, &mcp.Tool{
+		Name:        "list_modules",
+		Description: "List every module of the Einherjar framework with its purpose, import path, Go version, and sub-packages. Use this first to discover what the framework offers.",
+	}, func(ctx context.Context, req *mcp.CallToolRequest, _ listModulesInput) (*mcp.CallToolResult, listModulesOutput, error) {
+		out := listModulesOutput{Modules: make([]moduleSummary, 0, len(idx.Modules))}
+		for _, m := range idx.Modules {
+			subs := make([]string, 0, len(m.SubPackages))
+			for _, sp := range m.SubPackages {
+				if sp.Name != "" {
+					subs = append(subs, sp.Name)
+				}
+			}
+			out.Modules = append(out.Modules, moduleSummary{
+				Name:        m.Name,
+				ImportPath:  m.ImportPath,
+				Purpose:     m.Purpose,
+				GoVersion:   m.GoVersion,
+				SubPackages: subs,
+			})
+		}
+		return jsonText(out), out, nil
+	})
+}
--- a/internal/tools/search_symbols.go
+++ b/internal/tools/search_symbols.go
@@ -0,0 +1,48 @@
+package tools
+
+import (
+	"context"
+
+	"code.nochebuena.dev/einherjar/mcp/internal/index"
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+)
+
+type searchSymbolsInput struct {
+	Query  string `json:"query" jsonschema:"text to match against symbol name, doc comment, sub-package, or module"`
+	Limit  int    `json:"limit,omitempty" jsonschema:"max results (default 25)"`
+	Module string `json:"module,omitempty" jsonschema:"restrict to one module by name"`
+	Kind   string `json:"kind,omitempty" jsonschema:"restrict to one kind: type, interface, func, method, const, var"`
+}
+
+type searchSymbolsOutput struct {
+	Results []index.Symbol `json:"results"`
+	Total   int            `json:"total"`
+}
+
+func registerSearchSymbols(s *mcp.Server, idx *index.Index) {
+	mcp.AddTool(s, &mcp.Tool{
+		Name:        "search_symbols",
+		Description: "Search Einherjar's exported symbols (types, interfaces, funcs, methods, consts, vars) by name or doc text. Optionally filter by module or kind. Use when you need to find where a type or function lives.",
+	}, func(ctx context.Context, req *mcp.CallToolRequest, args searchSymbolsInput) (*mcp.CallToolResult, searchSymbolsOutput, error) {
+		all := idx.SearchSymbols(args.Query, args.Limit*4+25)
+		filtered := all[:0]
+		for _, sym := range all {
+			if args.Module != "" && sym.Module != args.Module {
+				continue
+			}
+			if args.Kind != "" && sym.Kind != args.Kind {
+				continue
+			}
+			filtered = append(filtered, sym)
+		}
+		limit := args.Limit
+		if limit <= 0 {
+			limit = 25
+		}
+		if len(filtered) > limit {
+			filtered = filtered[:limit]
+		}
+		out := searchSymbolsOutput{Results: filtered, Total: len(filtered)}
+		return jsonText(out), out, nil
+	})
+}
--- a/internal/tools/tools.go
+++ b/internal/tools/tools.go
@@ -0,0 +1,48 @@
+// Package tools wires Einherjar MCP tools to a server. Each tool lives in its
+// own file alongside its input and output types.
+package tools
+
+import (
+	"encoding/json"
+
+	"code.nochebuena.dev/einherjar/mcp/internal/index"
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+)
+
+// Register binds every tool implemented in this package to s, sharing the
+// provided index as their backing knowledge.
+func Register(s *mcp.Server, idx *index.Index) {
+	registerListModules(s, idx)
+	registerGetModule(s, idx)
+	registerSearchSymbols(s, idx)
+	registerGetSymbol(s, idx)
+	registerListADRs(s, idx)
+	registerGetADR(s, idx)
+	registerGetExample(s, idx)
+	registerValidateSnippet(s, idx)
+	registerGetCompliance(s, idx)
+	registerGetChangelog(s, idx)
+}
+
+// jsonText returns a CallToolResult whose single text block is the JSON
+// encoding of v. The same value is also returned as the structured output,
+// so hosts that surface structured outputs get a typed payload.
+func jsonText(v any) *mcp.CallToolResult {
+	b, err := json.MarshalIndent(v, "", "  ")
+	if err != nil {
+		return &mcp.CallToolResult{
+			IsError: true,
+			Content: []mcp.Content{&mcp.TextContent{Text: "encode error: " + err.Error()}},
+		}
+	}
+	return &mcp.CallToolResult{
+		Content: []mcp.Content{&mcp.TextContent{Text: string(b)}},
+	}
+}
+
+func errorResult(msg string) *mcp.CallToolResult {
+	return &mcp.CallToolResult{
+		IsError: true,
+		Content: []mcp.Content{&mcp.TextContent{Text: msg}},
+	}
+}
--- a/internal/tools/validate_snippet.go
+++ b/internal/tools/validate_snippet.go
@@ -0,0 +1,82 @@
+package tools
+
+import (
+	"context"
+
+	"code.nochebuena.dev/einherjar/mcp/internal/index"
+	"code.nochebuena.dev/einherjar/mcp/internal/rules"
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+)
+
+type validateSnippetInput struct {
+	Code string `json:"code" jsonschema:"Go source code to validate against Einherjar conventions. A full file is preferred; a partial body will be wrapped automatically."`
+}
+
+type validateSnippetOutput struct {
+	Findings []rules.Finding `json:"findings"`
+	Summary  string          `json:"summary"`
+}
+
+func registerValidateSnippet(s *mcp.Server, _ *index.Index) {
+	mcp.AddTool(s, &mcp.Tool{
+		Name:        "validate_snippet",
+		Description: "Validate a Go snippet against Einherjar wiring conventions: lifecycle setup, logger configuration, env-var handling, server registration. Findings are advisory, not a substitute for go vet or the project's tests.",
+	}, func(ctx context.Context, req *mcp.CallToolRequest, args validateSnippetInput) (*mcp.CallToolResult, validateSnippetOutput, error) {
+		findings := rules.Run(args.Code)
+		if findings == nil {
+			findings = []rules.Finding{}
+		}
+		summary := summarise(findings)
+		out := validateSnippetOutput{Findings: findings, Summary: summary}
+		return jsonText(out), out, nil
+	})
+}
+
+func summarise(fs []rules.Finding) string {
+	if len(fs) == 0 {
+		return "No issues found — snippet follows Einherjar conventions."
+	}
+	var errs, warns, infos int
+	for _, f := range fs {
+		switch f.Severity {
+		case rules.SeverityError:
+			errs++
+		case rules.SeverityWarning:
+			warns++
+		case rules.SeverityInfo:
+			infos++
+		}
+	}
+	return pluralise(errs, "error", "errors") + ", " +
+		pluralise(warns, "warning", "warnings") + ", " +
+		pluralise(infos, "note", "notes")
+}
+
+func pluralise(n int, singular, plural string) string {
+	if n == 1 {
+		return "1 " + singular
+	}
+	return itoa(n) + " " + plural
+}
+
+func itoa(n int) string {
+	if n == 0 {
+		return "0"
+	}
+	neg := n < 0
+	if neg {
+		n = -n
+	}
+	var buf [20]byte
+	i := len(buf)
+	for n > 0 {
+		i--
+		buf[i] = byte('0' + n%10)
+		n /= 10
+	}
+	if neg {
+		i--
+		buf[i] = '-'
+	}
+	return string(buf[i:])
+}