groundwork-method 0.0.1 → 0.10.0

package/src/generators/flutter-app/generator.ts

@@ -0,0 +1,362 @@
+import {
+  formatFiles,
+  generateFiles,
+  Tree,
+  names,
+} from '@nx/devkit';
+import * as path from 'path';
+import { recordGeneratorProvenance } from '../shared/provenance';
+import {
+  promoteEngineerSkill,
+  deployStackDocs,
+  registerRunner,
+} from '../shared/scaffold-helpers';
+
+export interface FlutterAppGeneratorSchema {
+  name: string;
+  org?: string;
+}
+
+const BRAND_TOKENS_PATH = '.groundwork/config/brand-tokens.json';
+
+/** Palette roles the visual block commits to (templates/brand-tokens.md). */
+const PALETTE_ROLES = [
+  'primary',
+  'accent',
+  'surface',
+  'surfaceAlt',
+  'textBody',
+  'success',
+  'error',
+  'warning',
+  'info',
+] as const;
+
+/** Neutral defaults used when no visual block (or no tokens at all) exists.
+ *  Mirrors how cli-app degrades to a Tier-1 identity: the app still themes
+ *  coherently, it just wears a restrained default brand. */
+const NEUTRAL_PALETTE: Record<string, { light: string; dark: string }> = {
+  primary: { light: '#3b6fd4', dark: '#7da7ef' },
+  accent: { light: '#7a5fd4', dark: '#b3a1f0' },
+  surface: { light: '#fafafa', dark: '#17181c' },
+  surfaceAlt: { light: '#f0f1f4', dark: '#1f2127' },
+  textBody: { light: '#26282e', dark: '#e4e6eb' },
+  success: { light: '#2f9e6e', dark: '#5fc398' },
+  error: { light: '#cf4444', dark: '#ef7f7f' },
+  warning: { light: '#c08a1f', dark: '#e0b35f' },
+  info: { light: '#3b6fd4', dark: '#7da7ef' },
+};
+
+const NEUTRAL_TYPOGRAPHY = {
+  display: { family: 'Inter', weight: 600 },
+  body: { family: 'Inter', weight: 400 },
+};
+
+const NEUTRAL_RADIUS_PX = 8;
+
+/** Convert an OKLCH colour to sRGB hex. The visual block allows palette values
+ *  in OKLCH or #rrggbb (templates/brand-tokens.md); Dart's Color needs ARGB, so
+ *  the projection resolves OKLCH at generation time rather than shipping a
+ *  colour-math dependency into the app. Standard OKLab → linear sRGB → gamma. */
+function oklchToHex(l: number, c: number, hDeg: number): string {
+  const hRad = (hDeg * Math.PI) / 180;
+  const a = c * Math.cos(hRad);
+  const b = c * Math.sin(hRad);
+
+  const l_ = l + 0.3963377774 * a + 0.2158037573 * b;
+  const m_ = l - 0.1055613458 * a - 0.0638541728 * b;
+  const s_ = l - 0.0894841775 * a - 1.291485548 * b;
+
+  const L = l_ ** 3;
+  const M = m_ ** 3;
+  const S = s_ ** 3;
+
+  const lin = [
+    4.0767416621 * L - 3.3077115913 * M + 0.2309699292 * S,
+    -1.2684380046 * L + 2.6097574011 * M - 0.3413193965 * S,
+    -0.0041960863 * L - 0.7034186147 * M + 1.707614701 * S,
+  ];
+
+  const toByte = (x: number): number => {
+    const clamped = Math.min(1, Math.max(0, x));
+    const srgb =
+      clamped <= 0.0031308
+        ? 12.92 * clamped
+        : 1.055 * Math.pow(clamped, 1 / 2.4) - 0.055;
+    return Math.round(Math.min(1, Math.max(0, srgb)) * 255);
+  };
+
+  return lin
+    .map((x) => toByte(x).toString(16).padStart(2, '0'))
+    .join('');
+}
+
+/** Resolve a CSS colour string (#rgb, #rrggbb, or oklch(...)) to rrggbb hex.
+ *  Returns null when the value cannot be resolved, so callers fall back to the
+ *  neutral default instead of emitting broken Dart. */
+function cssColorToHex(value: unknown): string | null {
+  if (typeof value !== 'string') return null;
+  const v = value.trim();
+
+  const hex6 = v.match(/^#([0-9a-fA-F]{6})$/);
+  if (hex6) return hex6[1].toLowerCase();
+
+  const hex3 = v.match(/^#([0-9a-fA-F]{3})$/);
+  if (hex3) {
+    return hex3[1]
+      .toLowerCase()
+      .split('')
+      .map((ch) => ch + ch)
+      .join('');
+  }
+
+  const oklch = v.match(
+    /^oklch\(\s*([\d.]+)(%?)\s+([\d.]+)\s+([\d.]+)(?:deg)?\s*\)$/i,
+  );
+  if (oklch) {
+    const l = parseFloat(oklch[1]) / (oklch[2] === '%' ? 100 : 1);
+    const c = parseFloat(oklch[3]);
+    const h = parseFloat(oklch[4]);
+    if ([l, c, h].every((n) => Number.isFinite(n))) return oklchToHex(l, c, h);
+  }
+
+  return null;
+}
+
+/** Dart Color literal from an rrggbb hex string. Tolerates a leading `#`
+ *  (the neutral-default palette carries CSS-style values) so no path can
+ *  emit a malformed literal like `Color(0xFF#3B6FD4)`. */
+function dartColor(hex: string): string {
+  return `Color(0xFF${hex.replace(/^#/, '').toUpperCase()})`;
+}
+
+/** Parse a radius descriptor like "8px" / "0.5rem" / "12" into logical pixels. */
+function radiusToLogicalPx(value: unknown): number {
+  if (typeof value !== 'string' && typeof value !== 'number') {
+    return NEUTRAL_RADIUS_PX;
+  }
+  const m = String(value)
+    .trim()
+    .match(/^([\d.]+)\s*(px|rem)?$/i);
+  if (!m) return NEUTRAL_RADIUS_PX;
+  const n = parseFloat(m[1]);
+  if (!Number.isFinite(n)) return NEUTRAL_RADIUS_PX;
+  return (m[2] || 'px').toLowerCase() === 'rem' ? n * 16 : n;
+}
+
+interface ResolvedBrand {
+  palette: Record<string, { light: string; dark: string }>; // rrggbb hex
+  typography: {
+    display: { family: string; weight: number };
+    body: { family: string; weight: number };
+  };
+  radiusPx: number;
+  source: 'visual-block' | 'identity-only' | 'default';
+}
+
+/** Project the design system's brand tokens into theme inputs. Three cases,
+ *  mirroring the cli-app's token handling:
+ *   - a Tier 2 `visual` block → full projection (palette roles, typography, shape)
+ *   - Tier-1-only tokens → palette seeded from identity.primary/accent
+ *   - no tokens → the neutral default */
+function resolveBrand(tree: Tree): ResolvedBrand {
+  const palette: Record<string, { light: string; dark: string }> = {};
+  for (const role of PALETTE_ROLES) {
+    palette[role] = { ...NEUTRAL_PALETTE[role] };
+  }
+  const typography = {
+    display: { ...NEUTRAL_TYPOGRAPHY.display },
+    body: { ...NEUTRAL_TYPOGRAPHY.body },
+  };
+  let radiusPx = NEUTRAL_RADIUS_PX;
+  let source: ResolvedBrand['source'] = 'default';
+
+  if (!tree.exists(BRAND_TOKENS_PATH)) {
+    return { palette, typography, radiusPx, source };
+  }
+
+  let raw: any = null;
+  try {
+    raw = JSON.parse(tree.read(BRAND_TOKENS_PATH, 'utf-8') || '{}');
+  } catch {
+    return { palette, typography, radiusPx, source }; // malformed — neutral
+  }
+
+  const visual = raw?.visual;
+  if (visual && typeof visual === 'object') {
+    source = 'visual-block';
+    for (const role of PALETTE_ROLES) {
+      const entry = visual.palette?.[role];
+      const light = cssColorToHex(entry?.light);
+      const dark = cssColorToHex(entry?.dark);
+      if (light) palette[role].light = light;
+      if (dark) palette[role].dark = dark;
+    }
+    if (visual.typography?.display?.family) {
+      typography.display.family = String(visual.typography.display.family);
+      typography.display.weight =
+        Number(visual.typography.display.weight) || typography.display.weight;
+    }
+    if (visual.typography?.body?.family) {
+      typography.body.family = String(visual.typography.body.family);
+      typography.body.weight =
+        Number(visual.typography.body.weight) || typography.body.weight;
+    }
+    radiusPx = radiusToLogicalPx(visual.shape?.radiusBase);
+    return { palette, typography, radiusPx, source };
+  }
+
+  // Tier-1-only tokens: derive the brand colours from identity, keep the
+  // neutral chrome. This is the mechanical Tier-1 projection the brand-tokens
+  // contract requires of every consumer.
+  const identity = raw?.identity;
+  if (identity && typeof identity === 'object') {
+    source = 'identity-only';
+    const primary = cssColorToHex(identity.primary);
+    const accent = cssColorToHex(identity.accent);
+    if (primary) {
+      palette.primary = { light: primary, dark: primary };
+      palette.info = { light: primary, dark: primary };
+    }
+    if (accent) palette.accent = { light: accent, dark: accent };
+  }
+
+  return { palette, typography, radiusPx, source };
+}
+
+/** Render the generated Dart theme module. The palette file is the projection
+ *  artifact (regenerate, never hand-edit); app_theme.dart (a static template)
+ *  builds ThemeData from it. */
+function renderBrandPalette(brand: ResolvedBrand): string {
+  const lines: string[] = [];
+  lines.push('// GENERATED by the GroundWork flutter-app generator from');
+  lines.push(
+    '// .groundwork/config/brand-tokens.json — do not hand-edit this file.',
+  );
+  lines.push('//');
+  lines.push(
+    '// Re-run the design system to evolve the brand, then regenerate (or update',
+  );
+  lines.push(
+    '// this file to match brand-tokens.json). Widgets never read these constants',
+  );
+  lines.push(
+    '// directly: they consume Theme.of(context), built in app_theme.dart.',
+  );
+  lines.push(
+    '// See docs/principles/stack/flutter/widgets-and-composition.md — theming is',
+  );
+  lines.push('// a projection, not an authoring surface.');
+  lines.push(`// Projection source: ${brand.source}.`);
+  lines.push("import 'package:flutter/material.dart';");
+  lines.push('');
+  lines.push("/// The design system's visual block, projected into Dart.");
+  lines.push('abstract final class BrandPalette {');
+  lines.push('  // Palette roles — light theme.');
+  for (const role of PALETTE_ROLES) {
+    lines.push(
+      `  static const Color ${role}Light = ${dartColor(brand.palette[role].light)};`,
+    );
+  }
+  lines.push('');
+  lines.push('  // Palette roles — dark theme.');
+  for (const role of PALETTE_ROLES) {
+    lines.push(
+      `  static const Color ${role}Dark = ${dartColor(brand.palette[role].dark)};`,
+    );
+  }
+  lines.push('');
+  lines.push('  // Typography families (bundle the font assets to take effect).');
+  lines.push(
+    `  static const String displayFontFamily = '${brand.typography.display.family.replace(/'/g, '')}';`,
+  );
+  lines.push(
+    `  static const int displayFontWeight = ${brand.typography.display.weight};`,
+  );
+  lines.push(
+    `  static const String bodyFontFamily = '${brand.typography.body.family.replace(/'/g, '')}';`,
+  );
+  lines.push(
+    `  static const int bodyFontWeight = ${brand.typography.body.weight};`,
+  );
+  lines.push('');
+  lines.push('  // Shape.');
+  lines.push(`  static const double radiusBase = ${brand.radiusPx.toFixed(1)};`);
+  lines.push('}');
+  lines.push('');
+  return lines.join('\n');
+}
+
+export default async function (tree: Tree, options: FlutterAppGeneratorSchema) {
+  const serviceNames = names(options.name);
+  const projectRoot = `services/${serviceNames.fileName}`;
+  // Dart package names are lower_snake_case; the workspace slug is kebab-case.
+  const pubspecName = serviceNames.fileName.replace(/-/g, '_');
+  const org = options.org || 'com.example';
+
+  const templateOptions = {
+    ...options,
+    ...serviceNames,
+    pubspecName,
+    org,
+    tmpl: '', // required by generateFiles
+  };
+
+  generateFiles(
+    tree,
+    path.join(__dirname, '..', '..', '..', '..', 'src', 'generators', 'flutter-app', 'files'),
+    projectRoot,
+    templateOptions,
+  );
+
+  // Project brand-tokens.json's visual block into the Dart theme module.
+  tree.write(
+    `${projectRoot}/lib/ui/core/theme/brand_palette.dart`,
+    renderBrandPalette(resolveBrand(tree)),
+  );
+
+  deployStackDocs(tree, path.join(__dirname, '..', '..', '..', '..', 'src', 'generators', 'flutter-app', 'docs'));
+
+  // A Flutter app lives on pubspec and the Dart toolchain, not npm, and it has
+  // no Docker boot. It never joins docker-compose.yml or the package.json
+  // workspaces list; instead it registers as a native runner so `./dev` can
+  // report and tail it. autostart is false — `flutter run` needs a target
+  // device/emulator chosen interactively, so it is registered and runnable but
+  // not part of the unattended `./dev start` boot set.
+  registerRunner(tree, {
+    name: serviceNames.fileName,
+    kind: 'surface',
+    cmd: 'bash tool/flutter_exec.sh run',
+    cwd: projectRoot,
+    autostart: false,
+  });
+
+  promoteEngineerSkill(tree, 'groundwork-flutter-engineer');
+
+  await formatFiles(tree);
+
+  recordGeneratorProvenance(tree, 'flutter-app', options as unknown as Record<string, unknown>);
+
+  return () => {
+    const { execSync } = require('child_process');
+    try {
+      execSync('command -v flutter', { stdio: 'ignore', shell: '/bin/bash' });
+    } catch {
+      console.warn(
+        `flutter SDK not found — generation is complete, but the toolchain tiers are skipped.\n` +
+          `Install the Flutter SDK, then run: npx nx run ${serviceNames.fileName}:bootstrap`,
+      );
+      return;
+    }
+    try {
+      execSync(`bash tool/flutter_exec.sh bootstrap`, {
+        cwd: projectRoot,
+        stdio: 'inherit',
+      });
+    } catch (e) {
+      console.warn(
+        `Failed to bootstrap ${projectRoot}. Run 'npx nx run ${serviceNames.fileName}:bootstrap' manually.`,
+      );
+    }
+  };
+}

package/src/generators/flutter-app/schema.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "http://json-schema.org/schema",
+  "id": "flutter-app",
+  "title": "Flutter App",
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "The name of the Flutter application (surface slug)",
+      "$default": {
+        "$source": "argv",
+        "index": 0
+      },
+      "x-prompt": "What name would you like to use for the app?"
+    },
+    "org": {
+      "type": "string",
+      "description": "Reverse-domain organization identifier used for the Android/iOS bundle id at bootstrap time",
+      "default": "com.example"
+    }
+  },
+  "required": ["name"]
+}

package/src/generators/go-microservice/docs/principles/stack/go/concurrency.md

@@ -0,0 +1,123 @@
+---
+title: Concurrency
+description: Goroutine lifecycle, errgroup, context cancellation, and supervised concurrency in Go services.
+status: active
+last_reviewed: 2026-05-26
+---
+# Concurrency
+
+## TL;DR
+
+Every goroutine we launch has an owner. We use `errgroup.WithContext` as the default supervision primitive, pass context everywhere, and never leave a goroutine running past the lifetime of the work it was started for.
+
+## Why this matters
+
+A goroutine is cheap to start and invisible when it leaks. Service memory that grows slowly but never recovers is almost always leaked goroutines holding references. Cancellation signals that never propagate are why graceful shutdowns stall. Getting goroutine ownership right is not defensive programming — it is the minimum bar for production Go code.
+
+## The core rules
+
+### Never use bare `go func()`
+
+A bare `go func()` that fires and forgets is a goroutine with no owner and no cancellation path. We don't write them. Every `go` statement launches a goroutine that is either:
+
+1. Tracked by an `errgroup.Group` or `sync.WaitGroup` that the caller waits on, or
+2. A long-lived background worker started at program entry and shut down via a dedicated `context.Context` and `sync.WaitGroup` on the composition root.
+
+### `errgroup.WithContext` is the default
+
+For any fan-out work — fetching multiple resources concurrently, processing items in parallel — `errgroup.WithContext` is the idiomatic choice:
+
+```go
+g, ctx := errgroup.WithContext(ctx)
+
+g.Go(func() error {
+    return fetchTranscript(ctx, id)
+})
+g.Go(func() error {
+    return fetchMetadata(ctx, id)
+})
+
+if err := g.Wait(); err != nil {
+    return fmt.Errorf("fetching resources: %w", err)
+}
+```
+
+When the first goroutine returns an error, the derived `ctx` is cancelled, signalling the others to stop. `g.Wait()` collects and returns the first non-nil error after all goroutines exit.
+
+### Context propagation is non-negotiable
+
+Every function that launches goroutines accepts a `context.Context` and passes it down. Every goroutine checks `ctx.Done()` on any blocking operation — I/O, channel receives, sleeps:
+
+```go
+select {
+case result := <-ch:
+    process(result)
+case <-ctx.Done():
+    return ctx.Err()
+}
+```
+
+A goroutine that ignores its context will run past cancellation, block graceful shutdown, and mask errors. There are no exceptions.
+
+### Limit concurrency with semaphores
+
+Unconstrained fan-out (one goroutine per item in a slice) exhausts file descriptors and saturates downstream services. Use a semaphore channel to bound parallelism:
+
+```go
+const maxConcurrency = 10
+sem := make(chan struct{}, maxConcurrency)
+
+g, ctx := errgroup.WithContext(ctx)
+for _, item := range items {
+    item := item
+    sem <- struct{}{}
+    g.Go(func() error {
+        defer func() { <-sem }()
+        return process(ctx, item)
+    })
+}
+if err := g.Wait(); err != nil {
+    return fmt.Errorf("processing items: %w", err)
+}
+```
+
+### Shared state: channels first, mutexes second
+
+When goroutines need to coordinate, pass ownership via channels rather than sharing pointers through mutexes. Channels make the ownership transfer explicit and visible. Use a `sync.Mutex` when a channel would be awkward — for example, protecting a map that is read from many goroutines and written to occasionally.
+
+Never access shared state without synchronisation. The Go race detector (`-race`) is a required gate in CI.
+
+## Graceful shutdown
+
+Background workers started at program entry must respect the root context. The composition root in `cmd/` creates a context cancelled by `SIGTERM`/`SIGINT`, and every long-lived worker selects on `ctx.Done()` to exit:
+
+```go
+func (w *Worker) Run(ctx context.Context) error {
+    for {
+        select {
+        case <-ctx.Done():
+            return nil
+        case job := <-w.queue:
+            if err := w.process(ctx, job); err != nil {
+                // log, metric, continue — or propagate if fatal
+            }
+        }
+    }
+}
+```
+
+The composition root waits on all workers before the process exits. A service that kills itself with `os.Exit` rather than waiting for goroutines to drain is a service that drops in-flight requests and corrupts state.
+
+## Anti-patterns
+
+- **Fire-and-forget goroutines.** If you don't track it, you don't own it.
+- **Sharing context derivations across goroutines.** Each goroutine that needs cancellation derives its own from the parent via `errgroup.WithContext` or `context.WithCancel`.
+- **Goroutines in `init()` or package-level `var`.** Goroutines belong in functions with explicit lifecycle management.
+- **Infinite retry loops without backoff and cancellation.** A retry loop that ignores `ctx.Done()` will spin forever after shutdown.
+- **Mutexes without deferred unlock.** Always `defer mu.Unlock()` immediately after acquiring the lock.
+
+## Further reading
+
+- [sync/errgroup package](https://pkg.go.dev/golang.org/x/sync/errgroup) — the official docs with examples.
+- *The Go Memory Model* (golang.org/ref/mem) — what happens before what, and why it matters.
+- *Concurrency in Go*, Katherine Cox-Buday — patterns and pitfalls from production experience.

package/src/generators/go-microservice/docs/principles/stack/go/index.md

@@ -0,0 +1,70 @@
+---
+title: Go Services
+description: Idiomatic Go, a pure core with swappable edges, error handling, concurrency, and the shape of a Go microservice.
+status: active
+last_reviewed: 2026-05-26
+---
+# Go Services
+
+## TL;DR
+
+Our Go code is boring on purpose. It leans into the standard library, uses interfaces only where they earn their keep, treats errors as values with context, and structures every service as a pure core wrapped by swappable edges — the inward-dependency rule written the Go way.
+
+## Why this matters
+
+Go rewards the engineer who resists cleverness. A Go codebase that reads like the standard library is one that new engineers — and AI agents — can contribute to the day they arrive. A Go codebase that imports a dozen frameworks and wraps every primitive in a "clean" abstraction is one where understanding costs precede any productive work. Keeping the core service legible is the highest-leverage investment we make.
+
+## Our principles
+
+### 1. Standard library first
+
+`net/http`, `context`, `database/sql` — the standard library is the default, and we reach for a third-party package only when the standard library demonstrably cannot do the job. Frameworks that "wrap" the standard library to make it "easier" usually make it harder to reason about and harder for a new reader to follow.
+
+### 2. A pure core, swappable edges
+
+Every service is a thin HTTP handler at the edge that extracts and validates inputs, an application service that orchestrates, domain types that hold rules, and interfaces — `Repository`, `MessageQueue`, `TextGenerator` — declared in the core package that consumes them, with Postgres-backed (and other technology-named) implementations at the edge. Packages nest under `internal/`: `internal/core/domain` and `internal/core/service` (the latter holds both the orchestration **and** the interfaces it calls), technology-named edge packages (`internal/postgres`, `internal/kafka`, `internal/pubsub`, `internal/httpclient`, `internal/websocket`, `internal/llm`), and `internal/entrypoints/api` for the HTTP edge, with composition roots in `cmd/`. Exported interfaces declared at the point of use, concrete edge types returned. `depguard` (in `.golangci.yml.template`) fails the build if `internal/core/...` imports an edge package — the inward-flow rule is a real gate, not a convention.
+
+### 3. Errors are values, and they carry context
+
+We wrap errors with `fmt.Errorf("doing X: %w", err)` when adding context, and we inspect them with `errors.Is` and `errors.As` at the boundary. We *never* `panic` in service code; `panic` is reserved for truly unrecoverable conditions (a nil interface where the type system should have prevented it) and is recovered only at the HTTP boundary. Sentinel errors are defined where the caller must branch on them; structured error types are defined where the caller needs detail.
+
+### 4. Context is threaded everywhere
+
+Every function that does I/O takes a `context.Context` as its first parameter. Cancellation and deadlines are respected. A goroutine that outlives its parent context without explicit opt-in is a bug. `context.Background()` appears only at program entry points and in tests.
+
+### 5. Concurrency is simple or explicit
+
+`go` statements that fire-and-forget are banned; every goroutine is tracked by a `sync.WaitGroup`, an `errgroup.Group`, or a channel that signals completion. Leaked goroutines are how a service slowly eats its memory. Shared state is accessed through channels by default, through mutexes when a channel would be awkward, and never through silence.
+
+### 6. Interfaces are defined by consumers
+
+We define interfaces in the package that consumes them — the "accept interfaces, return structs" rule. A package that defines an interface for its own use is leaking its internals as a public contract. Small interfaces (one to three methods) compose well; wide interfaces are a smell.
+
+### 7. Dependency injection is manual and explicit
+
+We do not use runtime dependency-injection frameworks. Dependencies are passed into constructors, and the composition happens in a `cmd/` entry point. This is the "composition root" pattern, and in Go it is both trivial and powerful — every dependency is visible at build time, and cycles are impossible by construction.
+
+### 8. Tests use the real thing where possible
+
+Service tests spin up a real Postgres container via Testcontainers and exercise the handler through HTTP. We mock only the expensive external edges (model clients, third-party APIs). See [Testing](testing.md) for Go-specific patterns.
+
+## Related docs
+
+- [Concurrency](concurrency.md) — goroutine lifecycle, errgroup, and supervised concurrency.
+- [Testing](testing.md) — Go honeycomb testing with Testcontainers and httptest.
+
+## Anti-patterns we reject
+
+- **Framework-flavoured Go.** Heavy router libraries, "web framework" abstractions, ORMs that rewrite your queries. The standard library is enough.
+- **`interface{}` or `any` as a type.** Except at the boundary of reflection-based code, `any` is a signal you lost the type war. Name the type.
+- **Package-level mutable state.** Config, loggers, metrics registries stored in package variables. Inject them, always.
+- **Goroutines without supervision.** If you launch it, you own its lifetime. Track it.
+- **`init()` functions that do work.** `init` is for registering, not for running. Work belongs in `main`.
+- **Pointer-to-struct when a value would do.** Pointers imply "this may be nil or may be mutated." If neither is true, pass the value.
+
+## Further reading
+
+- *The Go Programming Language*, Donovan & Kernighan — the canonical text.
+- *100 Go Mistakes and How to Avoid Them*, Teiva Harsanyi — a cadastre of the gotchas that bite real codebases.
+- *Dave Cheney's blog* ([dave.cheney.net](https://dave.cheney.net)) — the single best source on Go idioms, errors, and testing.
+- *The Go Memory Model* (golang.org/ref/mem) — read it at least once if you are writing concurrent code.