Group topics by category, lint brief format, restructure and extend briefs

.github/workflows/check.yml

@@ -0,0 +1,20 @@
+name: Check briefs
+
+on:
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.12'
+      - run: python scripts/lint_briefs.py
+      - run: python -m pip install -r requirements-docs.txt
+      - run: zensical build --clean --strict

.github/workflows/pages.yml

@@ -25,6 +25,7 @@ jobs:
       - uses: actions/setup-python@v6
         with:
           python-version: '3.12'
+      - run: python scripts/lint_briefs.py
       - run: python -m pip install -r requirements-docs.txt
       - run: zensical build --clean --strict
       - uses: actions/configure-pages@v6

AGENTS.md

@@ -6,9 +6,11 @@ This repo is a set of concise topic briefs for technical interview prep. The rea
 
 - `docs/topics/` — one brief per topic (e.g. `docs/topics/golang.md`).
 - `docs/index.md` — the reading site's homepage.
+- `scripts/lint_briefs.py` — checks the format rules below; CI runs it with the strict site build on every pull request.
 - `.agents/skills/quiz/` — the `quiz` skill, which quizzes the user on brief concepts. `.claude/skills/quiz` is a symlink to it so Claude Code and Codex share one copy.
 - File names are lowercase, single word or kebab-case.
 - `README.md` and `docs/index.md` list every topic with a link and a one-line summary, and `zensical.toml` lists it in the site nav. Update all three when adding or renaming a file.
+- Topics are grouped the same way in all three: **Fundamentals**, **Languages**, **Web**, **Infrastructure**, **Domains** — groups ordered by breadth, topics alphabetical within a group.
 
 ## Target format
 
@@ -41,12 +43,12 @@ What experienced Go engineers forget before an interview, grouped by subtopic.
 
 - **Title**: `# <Topic>` (e.g. `# Go`, `# Distributed Systems`). No "Cheatsheet" suffix.
 - **Intro**: one line: "What experienced <topic> engineers forget before an interview, grouped by subtopic." Adjust wording for non-language topics (e.g. "Key system design building blocks and trade-offs, grouped by subtopic.").
-- **`##` = subtopic** (Concurrency, Memory management, …). Named, not numbered. Ordered by how often the area comes up in interviews.
-- **`###` = concept** — a noun phrase (`### Scheduler (GMP)`, `### Isolation anomalies`), never a question, no numbers. Each concept should be self-contained: the quiz picks `###` headings at random.
+- **`##` = subtopic** (Concurrency, Memory management, …). Named, not numbered. Ordered by how often the area comes up in interviews. At least 2 concepts each; fold a lone concept into a related subtopic.
+- **`###` = concept** — a noun phrase (`### Scheduler (GMP)`, `### Isolation anomalies`), never a question, no numbers. Each concept should be self-contained (no "as above"): the quiz picks `###` headings at random.
 - **Body of a concept**: 2–6 bullets, or one short paragraph, or one compact table. One fact per bullet, one line where possible.
 - **Tables** for comparisons and matrices (channel axioms, isolation levels vs anomalies, deployment strategies, promise combinators).
 - **Code** only when shorter than prose; ≤ 6 lines.
-- **Bold** the term or number worth memorizing — at most 2–3 per concept.
+- **Bold** the term or number worth memorizing — at most 3 per concept, not counting tables.
 - **Versions**: note when behavior changed ("since Go 1.22", "Python 3.14+", "Pectra, May 2025").
 - **Cross-topic**: never repeat a concept owned by another file; link to it instead: `see [security.md](security.md)`. Link to files, not anchors (the strict build validates anchors; only use one if you've checked the slug).
 - Suggested size: 5–10 sections, 3–8 concepts each. Shorter is better if nothing is lost.

README.md

@@ -8,24 +8,38 @@ Each topic in `docs/topics/` is a brief grouped by subtopic, covering what an ex
 
 ## Topics
 
-- [Go](docs/topics/golang.md) — concurrency, memory management, slices/maps/strings, types and interfaces, errors, standard library gotchas, modules, testing and profiling
-- [Algorithms](docs/topics/algorithms.md) — complexity, array and string patterns, sorting, data structures, graphs, dynamic programming, greedy methods, NP-hardness
-- [Distributed Systems](docs/topics/distributed.md) — theory, consistency models, replication, partitioning, consensus, clocks and IDs, transactions, conflict resolution, failure handling, Kafka and stream processing
-- [Ethereum](docs/topics/ethereum.md) — accounts and transactions, gas, EVM, security, upgradeability, signatures, PoS consensus, scaling, DeFi and MEV
-- [System Design](docs/topics/system.md) — interview framework, traffic and edge, real-time delivery, caching, data storage, async processing, rate limiting, reliability, architecture, classic designs
+### Fundamentals
+
+- [Algorithms](docs/topics/algorithms.md) — complexity, arrays and sequences, strings, sorting, data structures, graphs, dynamic programming, greedy and backtracking, NP-hardness
 - [Databases](docs/topics/database.md) — indexes, isolation, MVCC and locking, storage engines, query tuning, SQL gotchas, Redis and NoSQL, schema design, scaling
-- [Networking](docs/topics/networking.md) — TCP, HTTP/1.1 vs 2 vs 3, QUIC, DNS, IP addressing, NAT, MTU, BGP and anycast
-- [Operating Systems](docs/topics/os.md) — processes and signals, scheduling and cgroup throttling, virtual memory and OOM, file descriptors, epoll and io_uring, fsync, synchronization, perf tools
-- [AI Engineering](docs/topics/ai.md) — LLM fundamentals, inference and serving, RAG, fine-tuning, agents, tools and MCP, evaluation, cost, security
-- [DevOps](docs/topics/devops.md) — deployment strategies, containers, Kubernetes workloads/networking/operations, Terraform, GitOps
-- [AWS](docs/topics/aws.md) — IAM and KMS, VPC networking, compute, storage and databases, events, operations
-- [Security](docs/topics/security.md) — web vulnerabilities, auth and sessions, tokens and OAuth, access control, cryptography, TLS, supply chain, threat modeling
+- [Distributed Systems](docs/topics/distributed.md) — theory, consistency models, replication, partitioning, consensus, clocks and IDs, transactions, conflict resolution, failure handling, Kafka and stream processing
+- [Networking](docs/topics/networking.md) — TCP, keepalive and congestion control, HTTP/1.1 vs 2 vs 3, QUIC, DNS, IP addressing, NAT, MTU, BGP and anycast
+- [Operating Systems](docs/topics/os.md) — processes and signals, scheduling and cgroup throttling, virtual memory, OOM and cgroup limits, NUMA, file descriptors, epoll and io_uring, fsync, synchronization, perf tools
+- [System Design](docs/topics/system.md) — interview framework, load balancing, caching and consistency, storage choices, queues, rate limiting, reliability, architecture, probabilistic and geospatial structures, classic designs
+
+### Languages
+
+- [Go](docs/topics/golang.md) — concurrency, memory management, slices/maps/strings, types and interfaces, errors, standard library gotchas, modules and GODEBUG, testing, profiling and PGO
+- [JavaScript](docs/topics/javascript.md) — event loop, scope and closures, `this` and prototypes, numbers, async, modules, memory, metaprogramming, Node.js runtime, DOM events, recent additions
+- [Python](docs/topics/python.md) — runtime and the GIL, memory management, data structures, concurrency, gotchas, object model, functions, recent features, typing, tooling
 - [Rust](docs/topics/rust.md) — ownership and borrowing, lifetimes, traits, closures and iterators, smart pointers, error handling, concurrency, async, unsafe, macros and Cargo
-- [Python](docs/topics/python.md) — runtime and the GIL, memory management, data structures, concurrency, gotchas, object model, typing, tooling
-- [TypeScript](docs/topics/typescript.md) — type system semantics, narrowing, type-level programming, compilation, strictness, declarations, typing patterns
-- [JavaScript](docs/topics/javascript.md) — event loop, scope and closures, `this` and prototypes, numbers, async, modules, memory, DOM events, recent additions
-- [Backend](docs/topics/backend.md) — API design, idempotency and concurrency, service calls and webhooks, async work, data access, lifecycle, security, testing
-- [Frontend](docs/topics/frontend.md) — rendering strategies, browser pipeline, performance, caching, React internals and concurrency, state management, accessibility
+- [TypeScript](docs/topics/typescript.md) — type system semantics, narrowing, type-level programming, compilation and TypeScript 6/7, strictness, declarations, typing patterns
+
+### Web
+
+- [Backend](docs/topics/backend.md) — API design, idempotency and concurrency, service calls and webhooks, async work, data access, lifecycle and health, security, testing
+- [Frontend](docs/topics/frontend.md) — rendering strategies, browser pipeline, CSS, performance, caching, React rendering and hooks, state management, accessibility
+- [Security](docs/topics/security.md) — server-side and browser-side attacks, auth and sessions, tokens and OAuth, authorization, cryptography, TLS, supply chain, threat modeling
+
+### Infrastructure
+
+- [AWS](docs/topics/aws.md) — IAM and KMS, VPC networking, compute, storage and databases, events, operations
+- [DevOps](docs/topics/devops.md) — deployment strategies, containers, Kubernetes workloads/storage/networking/operations, Terraform, CI/CD and GitOps
+
+### Domains
+
+- [AI Engineering](docs/topics/ai.md) — LLM fundamentals, attention and MoE, reasoning models, inference and serving, RAG, fine-tuning, agents, tools and MCP, evaluation, cost, security
+- [Ethereum](docs/topics/ethereum.md) — accounts and transactions, gas, EVM, Solidity, calls and ABI, security, upgradeability, signatures and standards, PoS consensus, scaling, DeFi and MEV
 
 ## Quiz
 

docs/index.md

@@ -4,24 +4,38 @@ Topic briefs on what engineers forget before technical interviews, grouped by su
 
 ## Topics
 
-- [Go](topics/golang.md) — concurrency, memory management, slices/maps/strings, types and interfaces, errors, standard library gotchas, modules, testing and profiling
-- [Algorithms](topics/algorithms.md) — complexity, array and string patterns, sorting, data structures, graphs, dynamic programming, greedy methods, NP-hardness
-- [Distributed Systems](topics/distributed.md) — theory, consistency models, replication, partitioning, consensus, clocks and IDs, transactions, conflict resolution, failure handling, Kafka and stream processing
-- [Ethereum](topics/ethereum.md) — accounts and transactions, gas, EVM, security, upgradeability, signatures, PoS consensus, scaling, DeFi and MEV
-- [System Design](topics/system.md) — interview framework, traffic and edge, real-time delivery, caching, data storage, async processing, rate limiting, reliability, architecture, classic designs
+### Fundamentals
+
+- [Algorithms](topics/algorithms.md) — complexity, arrays and sequences, strings, sorting, data structures, graphs, dynamic programming, greedy and backtracking, NP-hardness
 - [Databases](topics/database.md) — indexes, isolation, MVCC and locking, storage engines, query tuning, SQL gotchas, Redis and NoSQL, schema design, scaling
-- [Networking](topics/networking.md) — TCP, HTTP/1.1 vs 2 vs 3, QUIC, DNS, IP addressing, NAT, MTU, BGP and anycast
-- [Operating Systems](topics/os.md) — processes and signals, scheduling and cgroup throttling, virtual memory and OOM, file descriptors, epoll and io_uring, fsync, synchronization, perf tools
-- [AI Engineering](topics/ai.md) — LLM fundamentals, inference and serving, RAG, fine-tuning, agents, tools and MCP, evaluation, cost, security
-- [DevOps](topics/devops.md) — deployment strategies, containers, Kubernetes workloads/networking/operations, Terraform, GitOps
-- [AWS](topics/aws.md) — IAM and KMS, VPC networking, compute, storage and databases, events, operations
-- [Security](topics/security.md) — web vulnerabilities, auth and sessions, tokens and OAuth, access control, cryptography, TLS, supply chain, threat modeling
+- [Distributed Systems](topics/distributed.md) — theory, consistency models, replication, partitioning, consensus, clocks and IDs, transactions, conflict resolution, failure handling, Kafka and stream processing
+- [Networking](topics/networking.md) — TCP, keepalive and congestion control, HTTP/1.1 vs 2 vs 3, QUIC, DNS, IP addressing, NAT, MTU, BGP and anycast
+- [Operating Systems](topics/os.md) — processes and signals, scheduling and cgroup throttling, virtual memory, OOM and cgroup limits, NUMA, file descriptors, epoll and io_uring, fsync, synchronization, perf tools
+- [System Design](topics/system.md) — interview framework, load balancing, caching and consistency, storage choices, queues, rate limiting, reliability, architecture, probabilistic and geospatial structures, classic designs
+
+### Languages
+
+- [Go](topics/golang.md) — concurrency, memory management, slices/maps/strings, types and interfaces, errors, standard library gotchas, modules and GODEBUG, testing, profiling and PGO
+- [JavaScript](topics/javascript.md) — event loop, scope and closures, `this` and prototypes, numbers, async, modules, memory, metaprogramming, Node.js runtime, DOM events, recent additions
+- [Python](topics/python.md) — runtime and the GIL, memory management, data structures, concurrency, gotchas, object model, functions, recent features, typing, tooling
 - [Rust](topics/rust.md) — ownership and borrowing, lifetimes, traits, closures and iterators, smart pointers, error handling, concurrency, async, unsafe, macros and Cargo
-- [Python](topics/python.md) — runtime and the GIL, memory management, data structures, concurrency, gotchas, object model, typing, tooling
-- [TypeScript](topics/typescript.md) — type system semantics, narrowing, type-level programming, compilation, strictness, declarations, typing patterns
-- [JavaScript](topics/javascript.md) — event loop, scope and closures, `this` and prototypes, numbers, async, modules, memory, DOM events, recent additions
-- [Backend](topics/backend.md) — API design, idempotency and concurrency, service calls and webhooks, async work, data access, lifecycle, security, testing
-- [Frontend](topics/frontend.md) — rendering strategies, browser pipeline, performance, caching, React internals and concurrency, state management, accessibility
+- [TypeScript](topics/typescript.md) — type system semantics, narrowing, type-level programming, compilation and TypeScript 6/7, strictness, declarations, typing patterns
+
+### Web
+
+- [Backend](topics/backend.md) — API design, idempotency and concurrency, service calls and webhooks, async work, data access, lifecycle and health, security, testing
+- [Frontend](topics/frontend.md) — rendering strategies, browser pipeline, CSS, performance, caching, React rendering and hooks, state management, accessibility
+- [Security](topics/security.md) — server-side and browser-side attacks, auth and sessions, tokens and OAuth, authorization, cryptography, TLS, supply chain, threat modeling
+
+### Infrastructure
+
+- [AWS](topics/aws.md) — IAM and KMS, VPC networking, compute, storage and databases, events, operations
+- [DevOps](topics/devops.md) — deployment strategies, containers, Kubernetes workloads/storage/networking/operations, Terraform, CI/CD and GitOps
+
+### Domains
+
+- [AI Engineering](topics/ai.md) — LLM fundamentals, attention and MoE, reasoning models, inference and serving, RAG, fine-tuning, agents, tools and MCP, evaluation, cost, security
+- [Ethereum](topics/ethereum.md) — accounts and transactions, gas, EVM, Solidity, calls and ABI, security, upgradeability, signatures and standards, PoS consensus, scaling, DeFi and MEV
 
 ## Quiz