docs(rules): add Diataxis, doc voice guidance, and Go hardening notes

- Add Diataxis framework + lightweight templates to documentation rules
- Add doc voice guidance to avoid "you/your" phrasing
- Add Go HTTP client hardening guidance and align Go skill + references

Author: d-padmanabhan

rules/210-go.mdc

@@ -333,6 +333,58 @@ tlsConfig := &tls.Config{
 _, err := db.ExecContext(ctx, "INSERT INTO users (email) VALUES ($1)", email)
 ```
 
+### HTTP Client Hardening (MUST)
+
+When calling network APIs (internal or external), apply these non-negotiable checks:
+
+- **MUST** bound response body reads before `io.ReadAll` / decode.
+- **MUST** cap server-provided retry hints (for example `Retry-After`) to a configured maximum.
+- **MUST** keep "raw"/"escape hatch" API naming and docs aligned with actual behavior.
+- **MUST NOT** expose exported mutable global registries (maps/slices) used in policy/guardrails.
+- **MUST** keep test-only helpers in `*_test.go` so they do not compile into production binaries.
+
+```go
+//  GOOD: Bound network body reads
+const maxResponseBodyBytes = 10 << 20 // 10 MiB
+
+func readBodySafe(r io.Reader) ([]byte, error) {
+    limited := io.LimitReader(r, maxResponseBodyBytes+1)
+    body, err := io.ReadAll(limited)
+    if err != nil {
+        return nil, fmt.Errorf("read response body: %w", err)
+    }
+    if len(body) > maxResponseBodyBytes {
+        return nil, fmt.Errorf("response body exceeds %d bytes", maxResponseBodyBytes)
+    }
+    return body, nil
+}
+
+//  GOOD: Cap Retry-After-derived delays
+func retryDelay(attempt int, retryAfter string, maxDelay time.Duration) time.Duration {
+    if d, ok := parseRetryAfter(retryAfter); ok {
+        if d > maxDelay {
+            return maxDelay
+        }
+        return d
+    }
+    return backoff(attempt, maxDelay)
+}
+
+//  BAD: Exported mutable global policy registry
+var KnownAccounts = map[string]Account{} // External packages can mutate this
+
+//  GOOD: Unexported registry + copy accessor
+var knownAccounts = map[string]Account{}
+
+func KnownAccounts() map[string]Account {
+    out := make(map[string]Account, len(knownAccounts))
+    for k, v := range knownAccounts {
+        out[k] = v
+    }
+    return out
+}
+```
+
 ---
 
 ## 2. Simplicity & Idiomatic Go
@@ -1354,6 +1406,90 @@ go test -race ./...
 govulncheck ./...
 ```
 
+### CI Gates (Hardening Extension - Recommended)
+
+Add semantic checks for rules that standard linters miss.
+
+```bash
+# Semgrep policy checks (custom)
+semgrep --config .semgrep/go-hardening.yaml ./...
+```
+
+**Sample pre-commit hook:**
+
+```yaml
+repos:
+  - repo: https://github.com/returntocorp/semgrep
+    rev: v1.129.0
+    hooks:
+      - id: semgrep
+        name: semgrep-go-hardening
+        args: ["--config", ".semgrep/go-hardening.yaml"]
+        files: "\\.go$"
+```
+
+**Sample `.semgrep/go-hardening.yaml`:**
+
+```yaml
+rules:
+  - id: go-unbounded-network-readall
+    message: "Bound network body reads with io.LimitReader or MaxBytesReader"
+    severity: ERROR
+    languages: [go]
+    patterns:
+      - pattern: io.ReadAll($BODY)
+      - pattern-not: io.ReadAll(io.LimitReader($BODY, ...))
+
+  - id: go-retry-after-without-cap
+    message: "Cap Retry-After derived delay to configured max delay"
+    severity: WARNING
+    languages: [go]
+    patterns:
+      - pattern: |
+          if $DELAY, $OK := parseRetryAfter(...); $OK {
+            return $DELAY
+          }
+
+  - id: go-exported-mutable-registry
+    message: "Avoid exported mutable map/slice globals for policy/guardrail registries"
+    severity: WARNING
+    languages: [go]
+    patterns:
+      - pattern-either:
+          - pattern: var $X = map[$K]$V{...}
+          - pattern: var $X = []$T{...}
+      - metavariable-regex:
+          metavariable: $X
+          regex: "^[A-Z].*"
+
+  - id: go-testing-helper-in-non-test-file
+    message: "Move test helpers/imports into *_test.go files"
+    severity: WARNING
+    languages: [go]
+    paths:
+      exclude:
+        - "*_test.go"
+    patterns:
+      - pattern-either:
+          - pattern: import "testing"
+          - pattern: import "net/http/httptest"
+```
+
+### How To Add New Hardening Checks (Rules + Skills)
+
+When adding a new Go hardening guardrail, update both the rule and skill
+layers so guidance and enforcement stay aligned:
+
+1. Add the normative requirement under **HTTP Client Hardening (MUST)** in this
+   file (`rules/210-go.mdc`).
+2. Add/extend a detection rule in the sample semgrep section (and in your repo's
+   actual `.semgrep/go-hardening.yaml` if present).
+3. Add an anti-pattern bullet under **Anti-Patterns (Automatic Rejection)**.
+4. Mirror the operator-facing summary in
+   `skills/go-rust-systems/SKILL.md` under **Mandatory Hardening Add-On (Go)**.
+5. Update at least one concrete example in `skills/go-rust-systems/references/`
+   so the new requirement is demonstrated in runnable code.
+
 ---
 
 ## 6. Common Mistakes & Anti-Patterns
@@ -2985,8 +3121,11 @@ func setupLogger(level string) *slog.Logger {
 -  Goroutines without lifecycle management
 -  Swallowed errors ("Don't just check errors, handle them gracefully")
 -  Global mutable state
+-  Unbounded network body reads (`io.ReadAll` without limit on response bodies)
+-  Uncapped server-derived retry/sleep delays (`Retry-After` without max cap)
 -  Logging secrets/PII
 -  Zero values that require initialization to be safe ("Make the zero value useful")
+-  Test-only helper code in non-`*_test.go` files
 
 ### Code Smells
 -  Channels for simple mutual exclusion (use mutexes)

rules/810-documentation.mdc

@@ -18,6 +18,93 @@ files:
 
 ## Documentation Strategy
 
+### Diataxis Framework (Recommended)
+
+Use Diataxis to keep documentation purpose-specific. Each document should have one primary mode.
+
+| Mode | Primary user need | Typical question it answers |
+|---|---|---|
+| Tutorial | Learn by doing | "How do I get started?" |
+| How-to guide | Complete a specific task | "How do I configure X in Y?" |
+| Reference | Look up facts quickly | "What are all flags/options?" |
+| Explanation | Understand concepts and tradeoffs | "Why is this designed this way?" |
+
+> [!IMPORTANT]
+> Do not mix documentation modes in one page unless there is a strong reason. If a page starts combining step-by-step onboarding with API option listings and architectural rationale, split it into separate pages and cross-link them.
+
+### Diataxis Decision Guide
+
+Before writing or editing docs, choose one mode first:
+
+- If the reader is learning from scratch, write a **Tutorial**
+- If the reader is trying to finish a concrete task, write a **How-to guide**
+- If the reader needs authoritative details, write a **Reference**
+- If the reader needs understanding and rationale, write an **Explanation**
+
+### Diataxis Templates (Lightweight)
+
+#### Tutorial template
+
+```markdown
+# <Goal-oriented tutorial title>
+
+## What you will build
+
+## Prerequisites
+
+## Step-by-step walkthrough
+1. ...
+2. ...
+
+## Verify success
+
+## Next steps
+```
+
+#### How-to guide template
+
+```markdown
+# How to <specific task>
+
+## Prerequisites
+
+## Steps
+1. ...
+2. ...
+
+## Validation
+
+## Troubleshooting
+```
+
+#### Reference template
+
+```markdown
+# <Feature/API> reference
+
+## Syntax / schema
+
+## Parameters / fields
+
+## Defaults and limits
+
+## Examples
+```
+
+#### Explanation template
+
+```markdown
+# <Concept> explained
+
+## Context
+
+## Mental model
+
+## Tradeoffs
+
+## Related decisions and alternatives
+```
+
 ### When to Use Documentation Websites
 
 **Use documentation websites** when:
@@ -147,6 +234,16 @@ docs/
 - Define technical terms
 - Use examples liberally
 
+### Voice (Avoid "you/your")
+
+Prefer **neutral** or **imperative** phrasing over second-person voice.
+
+- **Preferred**: "Run `make test`", "Set `ENV=prod`", "The operator should rotate keys weekly"
+- **Avoid**: "You should run `make test`", "Make sure your environment is set to prod"
+
+> [!NOTE]
+> This improves consistency across audiences (end-users, operators, reviewers) and makes docs read less like a conversation.
+
 ### Punctuation
 
 **Never use em dashes (—) or en dashes (–). Use hyphens (-) instead.**

skills/documentation-standards/SKILL.md

@@ -12,6 +12,22 @@ description: Documentation best practices including Markdown formatting, Mermaid
 3. **Show, Don't Just Tell**: Use examples and diagrams
 4. **Consistent Format**: Follow established patterns
 
+## Voice
+
+Prefer neutral/imperative phrasing - avoid "you/your" in professional docs.
+Canonical guidance: `rules/810-documentation.mdc`.
+
+## Diataxis Quick Guide
+
+Use one primary documentation mode per page:
+
+- **Tutorial** - learning by doing
+- **How-to guide** - task completion
+- **Reference** - factual lookup
+- **Explanation** - concepts and rationale
+
+Canonical Diataxis guidance lives in `rules/810-documentation.mdc`. Keep this skill concise and link back to the rule instead of duplicating detailed standards.
+
 ## README Structure
 
 ```markdown

skills/go-rust-systems/SKILL.md

@@ -78,6 +78,31 @@ func TestAdd(t *testing.T) {
 }
 ```
 
+### Mandatory Hardening Add-On (Go)
+
+For HTTP/API client code, always apply the hardening checks from
+`rules/210-go.mdc`:
+
+- Bound response reads before `io.ReadAll`
+- Cap `Retry-After` and server-derived delays
+- Avoid exported mutable policy/guardrail registries
+- Keep test helpers in `*_test.go`
+
+Use semgrep + pre-commit checks for these patterns because standard linting
+does not catch all of them reliably.
+
+### How To Maintain Rule/Skill Parity
+
+When you add a new Go hardening expectation:
+
+1. Add the requirement to `rules/210-go.mdc` under **HTTP Client Hardening (MUST)**.
+2. Add detection guidance (semgrep/pre-commit) in the same rule file.
+3. Mirror the short operational summary in this `SKILL.md` section.
+4. Update at least one concrete reference example under
+   `skills/go-rust-systems/references/`.
+
+This keeps policy (rules), agent behavior (skill), and examples in sync.
+
 ## Rust Quick Reference
 
 ### Essential Commands

skills/go-rust-systems/references/go-aws-integration.md

@@ -38,12 +38,18 @@ func NewS3Client(ctx context.Context, region string) (*s3.Client, error) {
 
 ```go
 import (
+    "errors"
+    "fmt"
+    "io"
+    "github.com/aws/aws-sdk-go-v2/aws"
     "github.com/aws/aws-sdk-go-v2/service/s3"
     "github.com/aws/aws-sdk-go-v2/service/s3/types"
     "github.com/aws/smithy-go"
 )
 
 func GetObject(ctx context.Context, client *s3.Client, bucket, key string) ([]byte, error) {
+    const maxObjectReadBytes = 10 << 20 // 10 MiB safety bound
+
     result, err := client.GetObject(ctx, &s3.GetObjectInput{
         Bucket: aws.String(bucket),
         Key:    aws.String(key),
@@ -63,7 +69,14 @@ func GetObject(ctx context.Context, client *s3.Client, bucket, key string) ([]by
     }
     defer result.Body.Close()
 
-    return io.ReadAll(result.Body)
+    body, err := io.ReadAll(io.LimitReader(result.Body, maxObjectReadBytes+1))
+    if err != nil {
+        return nil, fmt.Errorf("read object body: %w", err)
+    }
+    if len(body) > maxObjectReadBytes {
+        return nil, fmt.Errorf("object body exceeds %d bytes", maxObjectReadBytes)
+    }
+    return body, nil
 }
 ```
 

skills/go-rust-systems/references/go-testing.md

@@ -41,6 +41,10 @@ func FuzzParseURL(f *testing.F) {
 
 **Test Helpers:**
 
+> [!IMPORTANT]
+> Keep helper utilities that import `testing`/`httptest` in `*_test.go` files.
+> This prevents test scaffolding from being compiled into production binaries.
+
 ```go
 func setupTestDB(t *testing.T) *sql.DB {
     t.Helper()  // Marks this as a test helper