Introduction¶

The Technology Selection Guide is an opinionated, prescriptive, version-pinned reference for production Go services and TypeScript frontends. This chapter establishes the vocabulary, audiences, and conventions every other chapter inherits. Read this chapter before any other chapter — the prescriptive keywords defined here are not restated downstream.

TL;DR¶

The guide targets three audiences simultaneously: engineers planning new services, LLM agents grounding recommendations, and organizations forking the guide for internal use.
Every prescriptive sentence uses RFC 2119 / BCP 14 / RFC 8174 keywords (MUST, MUST NOT, SHOULD, SHOULD NOT, MAY) so that enforceability is unambiguous.
Each chapter is self-contained: a section extracted in isolation MUST give accurate guidance without reaching back to context elsewhere in the document.
Concrete reference paths from the canonical reference implementation appear ONLY inside Reference Implementation admonition blocks; body prose stays path-agnostic so adopting organizations MAY fork the guide without rewriting chapters.
Every chapter file carries last-reviewed: YYYY-MM-DD YAML frontmatter, and the review cadence is quarterly.

Why this choice¶

The guide is distributed outside its donor repository as a standalone document set. Forking organizations MUST be able to adopt the prose unchanged. To make that possible:

Prescriptive vocabulary. Plain-English phrases such as the bare imperative "do this" are ambiguous when forked into a different culture. RFC 2119 keywords are unambiguous and machine-greppable.
Chapter independence. LLM agents retrieve guide sections by vector similarity, not in narrative order. A section that points backward to "context elsewhere" loses meaning when retrieved alone.
Path-agnostic prose. Adopting organizations have different repository layouts. Concrete paths belong in clearly marked Reference Implementation callouts where the reader knows the example is illustrative, not prescriptive.
Versioned snapshots. The technology landscape moves fast. Each chapter publishes a pinned-versions snapshot dated to the last review so that the reader knows exactly when the recommendation was validated.

Prescriptive guidance¶

RFC 2119 / BCP 14 keyword definitions¶

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC 2119] [RFC 8174] when, and only when, they appear in all capitals, as shown here.

Practical restatements for ease of reference:

MUST / SHALL / REQUIRED — an absolute requirement. An implementation that does not satisfy this is non-conforming.
MUST NOT / SHALL NOT — an absolute prohibition. An implementation that does this is non-conforming.
SHOULD / RECOMMENDED — a strong recommendation. An implementer MAY deviate but MUST understand and document the trade-off.
SHOULD NOT / NOT RECOMMENDED — a strong discouragement under the same documentation discipline.
MAY / OPTIONAL — a truly optional choice. Both inclusion and omission are conforming.

Lowercase use of these words ("must", "should", "may") carries no RFC 2119 force. Lowercase usage is ordinary prose.

Audiences and how to read¶

The guide serves three audiences. Every chapter is written so each audience extracts value from the same prose.

Engineer planning a new Go service. Read end to end the first time. Each chapter follows a fixed shape (TL;DR → Why this choice → Prescriptive guidance → Reference Implementation callout → Pinned versions → Pitfalls → See also). After the first read, return to chapters by need. Engineers not building a Kubernetes operator MAY skip the Operator subsection of the Architecture chapter; engineers not deploying into restricted networks MAY defer the Air-Gap chapter until late in the project.
LLM agent grounding recommendations. Fetch /llms.txt for a citation-friendly table of contents and /llms-full.txt for the concatenated content. Every chapter section is independently coherent so retrieved chunks remain accurate. Heading hierarchy is predictable so subsections MAY be cited by anchor.
Adopting organization forking the guide. Body prose is path-agnostic. Adopting orgs MUST update the site_url, repo_url, and LICENSE attribution. Adopting orgs MAY swap the Reference Implementation admonitions for their own donor codebase or remove them outright; the path-agnostic main text remains correct either way.

Doc conventions¶

The first # heading in each chapter is the chapter title; there MUST be exactly one # heading per chapter. Major sections use ##, subsections use ###, and deeper detail uses ####.
Every prescriptive sentence MUST carry an explicit RFC 2119 keyword. Plain imperatives without a keyword are reserved for illustrative, non-prescriptive prose.
Each chapter MUST contain a Reference Implementation admonition formatted as an MkDocs Material !!! example block with a title of the form Reference Implementation: <reference-codebase>. Concrete reference-codebase paths MUST appear only inside that admonition; body prose uses path-agnostic forms such as <repo>/internal/<domain>/handler.go.
Each chapter MUST be self-contained. Backward cross-references to "earlier" material are forbidden because they break when sections are retrieved out of order. If a fact matters to two chapters, both chapters state it locally.
The pinned-versions snapshot table at the end of each chapter carries the date of the most recent review.

Review cadence¶

Every chapter file MUST carry last-reviewed: YYYY-MM-DD YAML frontmatter in ISO date format.
Reviews MUST occur at least quarterly. A review MAY conclude with "no content change" — the reviewer still bumps the date, certifying the chapter is accurate as of that date.
The pinned-versions snapshot table in each chapter MUST be dated to match the most recent review.

Reference Implementation: Pioneer

The doc conventions above are exercised by the canonical reference implementation. See pioneer/CLAUDE.md for the project-root principles that originated these conventions, and see the Reference Implementation admonitions in chapters 01-architecture.md through 11-multi-language.md for concrete code references that ground each prescription in real, shipped code.

Pinned versions (snapshot 2026-05-08)¶

The Introduction chapter has no runtime dependencies. The standards and tools referenced here are stable:

Reference	Version	Notes
RFC 2119	March 1997	Original keyword definitions
RFC 8174	May 2017	Capitalization clarification (BCP 14 update)
MkDocs Material	9.x	Admonition syntax used for callouts
Mermaid	10.x	Diagram syntax used in later chapters

Adopting orgs MUST validate these references against their own toolchain constraints at adoption time. The snapshot date above matches last-reviewed in this chapter's frontmatter.

Pitfalls¶

Lowercase RFC 2119 words. "should" in lowercase carries no force. Reviewers MUST treat capitalization as load-bearing and reject changes that downgrade an uppercase keyword to lowercase without justification.
Forgetting to bump last-reviewed. Reviews without a date bump leave readers unsure whether the chapter has been examined. Reviewers MUST bump the date even when no content changes.
Naming the donor codebase in body prose. Concrete reference paths and the donor codebase name MUST stay inside Reference Implementation admonition blocks so that forking organizations MAY replace the admonition without editing chapter prose.
Backward cross-references. Phrasing that points at "earlier" material breaks when LLM agents retrieve sections in isolation. Authors MUST restate the fact locally instead.
Adding a new chapter without updating mkdocs.yml nav and llms.txt. A chapter that is not in the nav is invisible to the sidebar and to the published llms-full.txt. The same teammate run that authors a chapter MUST extend both manifests.