autonomous-coding-toolkit 1.0.0

package/docs/lessons/0016-event-driven-cold-start-seeding.md

@@ -0,0 +1,44 @@
+---
+id: 16
+title: "Event-driven systems must seed current state on startup"
+severity: should-fix
+languages: [python, javascript, all]
+scope: [universal]
+category: integration-boundaries
+pattern:
+  type: semantic
+  description: "Event-driven system produces empty/wrong output on first boot before any events arrive"
+fix: "On startup, seed current state by fetching a snapshot via REST/query before subscribing to events"
+example:
+  bad: |
+    # WebSocket event-driven system
+    class Dashboard:
+        def __init__(self):
+            self.users = []  # Empty on startup!
+
+        def on_event(self, event):
+            if event.type == "user_join":
+                self.users.append(event.user)
+
+    # On first boot, dashboard is empty until first user joins
+  good: |
+    # Seed current state on startup
+    class Dashboard:
+        def __init__(self):
+            self.users = []
+            # Fetch current state before subscribing to events
+            self.users = api.get_all_users()  # Seed!
+
+        def on_event(self, event):
+            if event.type == "user_join":
+                self.users.append(event.user)
+---
+
+## Observation
+An event-driven system (e.g., WebSocket, MQTT, event stream) maintains state by processing events. On startup, before any events arrive, the system has no state. It produces an empty result, wrong result, or waits until an event triggers. Users see an empty dashboard or broken state until the first event.
+
+## Insight
+The root cause is treating events as the only state source. Events represent *changes*, not current state. In steady state, events keep the system up-to-date. But on first boot, there's no baseline — the system must fetch current state separately before subscribing to changes.
+
+## Lesson
+Event-driven systems must seed current state on startup. Before subscribing to events, fetch a snapshot (via REST API, database query, or cache) to populate initial state. Then subscribe to events to handle incremental changes. This ensures the system has correct state from the first moment it's needed, not after the first event.

package/docs/lessons/0017-copy-paste-logic-diverges.md

@@ -0,0 +1,43 @@
+---
+id: 17
+title: "Copy-pasted logic between modules diverges silently"
+severity: should-fix
+languages: [all]
+scope: [universal]
+category: integration-boundaries
+pattern:
+  type: semantic
+  description: "Two modules independently implement the same logic and diverge when only one is updated"
+fix: "Extract shared logic to a single module imported by both consumers"
+example:
+  bad: |
+    # module_a.py
+    def parse_date(s):
+        return datetime.strptime(s, "%Y-%m-%d").date()
+
+    # module_b.py (copy-paste)
+    def parse_date(s):
+        return datetime.strptime(s, "%Y-%m-%d").date()
+
+    # Later, module_a is updated to handle ISO format
+    # module_b is forgotten and still only handles %Y-%m-%d
+  good: |
+    # utils.py (shared)
+    def parse_date(s):
+        return datetime.strptime(s, "%Y-%m-%d").date()
+
+    # module_a.py
+    from utils import parse_date
+
+    # module_b.py
+    from utils import parse_date
+---
+
+## Observation
+Two modules that compute the same thing independently will diverge silently over time. One module gets updated to handle a new case or bug fix, the other doesn't. Now they behave differently for the same input, and there's no error — both modules are "working" within their own scope.
+
+## Insight
+The root cause is code duplication at creation time. Copy-pasting logic is faster initially but creates a maintenance burden: every fix must be applied twice. If the person fixing module_a doesn't know module_b exists, the fix isn't applied there. The divergence is invisible until the different behaviors cause a bug.
+
+## Lesson
+Never copy-paste logic between modules. Extract it to a shared utility that both import. This ensures changes are made once and benefit both consumers. If you find the same logic in two places, refactor immediately — treat it as a red flag that future divergence is likely.

package/docs/lessons/0018-layer-passes-pipeline-broken.md

@@ -0,0 +1,45 @@
+---
+id: 18
+title: "Every layer passes its test while full pipeline is broken"
+severity: should-fix
+languages: [all]
+scope: [universal]
+category: integration-boundaries
+pattern:
+  type: semantic
+  description: "Each pipeline layer passes unit tests independently while the full pipeline is broken at integration seams"
+fix: "Add at least one end-to-end test tracing a single input through every layer"
+example:
+  bad: |
+    # Layer 1: Data fetch (passes)
+    test_fetch: reads from mock DB, returns [User, User, User] ✓
+
+    # Layer 2: Transform (passes)
+    test_transform: receives list, returns transformed list ✓
+
+    # Layer 3: Store (passes)
+    test_store: receives list, writes to mock storage ✓
+
+    # Integration: Broken!
+    # Layer 2 returns dict, Layer 3 expects list → crash
+  good: |
+    # Unit tests for each layer (all pass)
+    test_fetch, test_transform, test_store (as above)
+
+    # Plus: E2E test tracing one record through all layers
+    test_full_pipeline:
+      input = create_test_user()
+      result = fetch(input)  # Layer 1
+      result = transform(result)  # Layer 2
+      store(result)  # Layer 3
+      assert result_in_storage(result)  # Verify end-to-end
+---
+
+## Observation
+A multi-layer pipeline (data fetch → transform → store → API → UI) has each layer passing its unit tests independently. The full pipeline is broken at the integration seams: layer 1 returns a list, layer 2 expects a dict; layer 3 stores to file, layer 4 queries a database; fields have different names at each boundary.
+
+## Insight
+The root cause is testing each layer in isolation with mocked inputs/outputs. Each layer is correct for its inputs, but the outputs of one layer don't match the inputs of the next. The seams are never tested because each test stops at layer boundaries.
+
+## Lesson
+Always add at least one end-to-end test that traces a single input through every layer of the pipeline. Don't mock layer outputs — let real data flow through the entire system. This catches integration mismatches immediately. E2E tests are not a replacement for unit tests, they're a mandatory complement.

package/docs/lessons/0019-systemd-envfile-ignores-export.md

@@ -0,0 +1,41 @@
+---
+id: 19
+title: "systemd EnvironmentFile ignores `export` keyword"
+severity: should-fix
+languages: [shell]
+scope: [framework:systemd]
+category: silent-failures
+pattern:
+  type: syntactic
+  regex: "EnvironmentFile="
+  description: "systemd EnvironmentFile silently ignores lines with export prefix"
+fix: "Use a bash wrapper (ExecStart=/bin/bash -c '. ~/.env && exec binary') or strip export from the file"
+example:
+  bad: |
+    # ~/.env file
+    export API_KEY=secret123
+    export DEBUG=true
+
+    # systemd service
+    [Service]
+    EnvironmentFile=~/.env
+    # systemd ignores export prefix, loads nothing
+  good: |
+    # Either: strip export from the file
+    # ~/.env
+    API_KEY=secret123
+    DEBUG=true
+
+    # Or: use bash wrapper
+    [Service]
+    ExecStart=/bin/bash -c '. ~/.env && exec /usr/bin/myapp'
+---
+
+## Observation
+A systemd service uses `EnvironmentFile=~/.env` with a `.env` file that contains `export VAR=value` syntax. The service starts without error but has empty environment variables. The `export` prefix is silently ignored by systemd's EnvironmentFile parser.
+
+## Insight
+systemd `EnvironmentFile` expects the format `KEY=value` only. The `export` keyword is shell syntax, not systemd syntax. When systemd sees `export KEY=value`, it either ignores the entire line or only parses the part after the `=`, leaving the variable unset. No error is logged — the service just runs with an incomplete environment.
+
+## Lesson
+systemd `EnvironmentFile` requires `KEY=value` format without `export`. Either: (1) maintain two files — one for shell-sourcing (with `export`) and one for systemd (without `export`), or (2) use a bash wrapper (`ExecStart=/bin/bash -c '. ~/.env && exec myapp'`) that sources the shell-format file. Never mix systemd EnvironmentFile with shell export syntax.

package/docs/lessons/0020-persist-state-incrementally.md

@@ -0,0 +1,44 @@
+---
+id: 20
+title: "Persist state incrementally before expensive work"
+severity: should-fix
+languages: [all]
+scope: [universal]
+category: silent-failures
+pattern:
+  type: semantic
+  description: "Long-running process saves state only at the end, losing all progress on crash"
+fix: "Checkpoint state after each logical unit of work"
+example:
+  bad: |
+    def process_large_dataset(items):
+        results = []
+        for item in items:
+            result = expensive_operation(item)
+            results.append(result)
+        save_results(results)  # All progress lost if crash occurs here
+  good: |
+    def process_large_dataset(items):
+        for i, item in enumerate(items):
+            result = expensive_operation(item)
+            save_checkpoint(result, i)  # State saved after each unit
+---
+
+## Observation
+
+Long-running processes that accumulate work and save state only at the end are vulnerable to catastrophic data loss. A 2-hour batch job that crashes during the final save step restarts from zero, repeating 2 hours of work.
+
+## Insight
+
+State persistence is a trade-off between granularity and overhead. The instinct is to minimize I/O by batching writes, but this violates the fundamental reliability principle: *work that has been completed should not be lost*. Progress checkpoints have minimal overhead (typically <5% in database-backed systems) and prevent the infinite-restart failure mode.
+
+## Lesson
+
+Checkpoint state after each logical unit of work, not just at the end. Use one of these patterns:
+
+- **Database transactions**: Commit after each logical unit, not at the end
+- **State files**: Write incremental snapshots (e.g., `batch_001_complete.json`)
+- **Message queue acknowledgment**: Ack each message after processing, not at the end of the batch
+- **Progress markers**: Track completed work in a separate file, read on startup to resume
+
+Always verify the checkpoint write succeeds before proceeding. If a process crashes, it should resume from the last checkpoint, never restart from zero.

package/docs/lessons/0021-dual-axis-testing.md

@@ -0,0 +1,48 @@
+---
+id: 21
+title: "Dual-axis testing: horizontal sweep + vertical trace"
+severity: should-fix
+languages: [all]
+scope: [universal]
+category: integration-boundaries
+pattern:
+  type: semantic
+  description: "Testing only endpoints (horizontal) or only data flow (vertical) misses entire bug classes"
+fix: "Run both horizontal sweep (every endpoint) and vertical trace (one input through all layers)"
+example:
+  bad: |
+    # Only test endpoints exist
+    def test_api_responses():
+        assert client.get('/users').status_code == 200
+        assert client.get('/users/1').status_code == 200
+    # Missing: verify data actually flows and transforms correctly
+  good: |
+    # Horizontal: every endpoint responds
+    assert client.get('/users').status_code == 200
+    # Vertical: one user through all layers
+    response = client.post('/users', data={'name': 'Alice'})
+    user_id = response.json()['id']
+    assert client.get(f'/users/{user_id}').json()['name'] == 'Alice'
+---
+
+## Observation
+
+Many test suites validate that endpoints exist and return 2xx status codes, but never verify that data flows end-to-end. A bug where data enters the pipeline but never reaches the database passes horizontal testing but fails in production.
+
+## Insight
+
+Integration bugs exist at layer boundaries: serialization, deserialization, state transitions, and persistence. Horizontal testing (every endpoint exists) confirms the surface. Vertical testing (one input through all layers) confirms the pipeline. Both are required because they catch different bug classes:
+
+- **Horizontal** → missing endpoints, wrong status codes
+- **Vertical** → data transformation bugs, missing persistence, state inconsistency
+
+Testing only one axis misses 50% of integration bugs.
+
+## Lesson
+
+After implementing a multi-layer system (API → logic → database, or UI → service → cache), always run dual-axis testing:
+
+1. **Horizontal sweep**: Hit every endpoint/CLI command/UI action. Confirm each responds correctly.
+2. **Vertical trace**: Submit one real input and trace it through every layer to the final output. Confirm data flows end-to-end and state accumulates correctly.
+
+Execute vertical first (catches more bugs per minute), then horizontal (completeness check). Both must pass before claiming readiness. Document the vertical trace as a test case you can re-run.

package/docs/lessons/0022-jsx-factory-shadowing.md

@@ -0,0 +1,43 @@
+---
+id: 22
+title: "Build tool JSX factory shadowed by arrow params"
+severity: blocker
+languages: [javascript, typescript]
+scope: [framework:preact]
+category: silent-failures
+pattern:
+  type: syntactic
+  regex: "\.map\\(h\\s*=>"
+  description: "Arrow function parameter shadows build tool JSX factory injection"
+fix: "Never use single-letter variable names that match build tool injections (h, React)"
+example:
+  bad: |
+    import { h } from 'preact';
+    const items = users.map(h => (
+      <div key={h.id}>{h.name}</div>  // h refers to user, not JSX factory
+    ));  // JSX transform fails silently
+  good: |
+    import { h } from 'preact';
+    const items = users.map(user => (
+      <div key={user.id}>{user.name}</div>
+    ));  // Clear intent, no shadowing
+---
+
+## Observation
+
+Build tools like esbuild inject `h` (or `React` in some configs) as a JSX factory at the top of each file. When code uses `h` as an arrow function parameter (`.map(h => ...)`), the parameter shadows the injected factory. JSX elements become malformed, rendering silently fails with no error.
+
+## Insight
+
+This is a tooling footgun: the injection is invisible but syntactically valid. A user object parameter named `h` is reasonable in isolation, but creates a silent failure when combined with JSX. The build tool cannot detect this because it happens after transformation.
+
+## Lesson
+
+Never use `h`, `React`, or other build-tool-injected names as local variable or parameter names:
+
+- Avoid: `.map(h => ...)`, `.forEach(React => ...)`
+- Use: `.map(user => ...)`, `.forEach(Component => ...)`
+
+Apply this consistently across your codebase. In code review, flag any single-letter parameter names that match build tool injections. The cost of renaming is zero; the cost of debug time is unbounded.
+
+For teams using JSX, add a linter rule (ESLint with `no-shadow` + `no-loop-func`) to catch this pattern automatically.

package/docs/lessons/0023-static-analysis-spiral.md

@@ -0,0 +1,51 @@
+---
+id: 23
+title: "Static analysis spiral -- chasing lint fixes creates more bugs"
+severity: should-fix
+languages: [all]
+scope: [universal]
+category: test-anti-patterns
+pattern:
+  type: semantic
+  description: "Implementing lint fixes triggers new warnings in a cascading spiral"
+fix: "Set a lint baseline, only fix violations in code you're actively changing"
+example:
+  bad: |
+    # Run linter, find 150 issues
+    pylint mymodule.py  # 150 violations
+    # Start fixing: add type hints, remove unused imports, refactor
+    # After 1 hour: 140 violations, but 3 bugs introduced in refactoring
+    # Keep fixing: now 120 violations, but more subtle bugs
+  good: |
+    # Establish baseline
+    pylint mymodule.py > baseline.txt  # 150 violations recorded
+    # Only fix violations in code you touch during feature work
+    # When implementing a function, clean that function's lints
+    # New commits don't expand scope beyond the feature
+---
+
+## Observation
+
+Linting systems are designed to improve code quality incrementally, but aggressive lint-chasing creates a secondary spiral: fixing style violations in unrelated code introduces logic bugs, which are harder to catch than style violations.
+
+## Insight
+
+Linting has two modes:
+
+1. **Prophylactic** (new code): enforce rules as you write
+2. **Curative** (old code): bulk-fix accumulated violations
+
+Curative mode is expensive when applied to a large codebase. Each refactor is a chance to introduce bugs, and scope expands unbounded. The instinct is to "make the codebase better while I'm at it," but that trades quality for coverage and usually loses the trade.
+
+## Lesson
+
+Set a lint baseline and fix violations only in code you're actively changing:
+
+1. Run the linter and record the baseline (e.g., `pylint mymodule.py > baseline.txt`)
+2. During feature work, when you touch a function, also fix that function's lints
+3. Never expand scope to fix unrelated violations
+4. New commits should show code cleanup *in the changed regions only*
+
+If you want to tackle accumulated tech debt, do it in a separate PR with a clear scope: "Refactor payment module for clarity — no logic changes." Run tests before and after to verify behavior is identical. Otherwise, lint fixes stay scoped to feature work.
+
+Avoid automated "fix all lints" commits — they're high-risk, low-review, and merge conflicts nightmare. Humans fix code they understand; linters fix code they can parse.

package/docs/lessons/0024-shared-pipeline-implementation.md

@@ -0,0 +1,55 @@
+---
+id: 24
+title: "Shared pipeline features must share implementation"
+severity: should-fix
+languages: [all]
+scope: [universal]
+category: integration-boundaries
+pattern:
+  type: semantic
+  description: "Two pipeline stages independently implement the same feature logic and produce different results"
+fix: "Both stages import from one module; if different languages, add contract tests"
+example:
+  bad: |
+    # Python: batch pipeline
+    def process_batch(items):
+        results = [transform(item) for item in items]
+        return results
+
+    # JavaScript: real-time pipeline (independently implemented)
+    function processStream(item) {
+        return transform(item);  // Slightly different logic
+    }
+  good: |
+    # Python shared logic
+    # pipeline/transform.py
+    def transform(item):
+        return item.value * 2
+
+    # batch.py
+    from pipeline.transform import transform
+    results = [transform(item) for item in items]
+
+    # For JavaScript, if needed separately:
+    # Add contract test: both versions produce identical output on test set
+---
+
+## Observation
+
+Pipelines often have multiple paths: batch processing, streaming, scheduled jobs. When each path independently implements logic like filtering, validation, or transformation, they diverge. One handles edge cases the other misses, producing inconsistent results.
+
+## Insight
+
+Feature logic encoded in multiple places creates a maintenance burden and a correctness risk. Each implementation is an opportunity for a bug; each update requires changes in N places. The root cause is treating pipeline stages as independent systems when they should share a common contract.
+
+## Lesson
+
+When multiple pipeline stages implement the same feature:
+
+1. **Same language**: Extract logic to a shared module; all stages import from it.
+2. **Different languages**: Implement once in the language closest to the data source (usually Python for batch), then wrap in contract tests that verify the other language's implementation produces identical output on a test dataset.
+3. **External service**: Deploy once, both stages call the API.
+
+Document the contract: "transform() must handle null, empty string, and values >1000." Then verify both implementations satisfy it. When bugs are found, fix once, verify all paths, deploy once.
+
+This is the DRY principle applied to distributed systems: don't repeat business logic across process boundaries.

package/docs/lessons/0025-defense-in-depth-all-entry-points.md

@@ -0,0 +1,65 @@
+---
+id: 25
+title: "Defense-in-depth: validate at all entry points"
+severity: should-fix
+languages: [all]
+scope: [universal]
+category: integration-boundaries
+pattern:
+  type: semantic
+  description: "Input validation exists at one entry point but not others (API, CLI, WebSocket, cron)"
+fix: "Centralize validation in a shared function called by all entry points"
+example:
+  bad: |
+    # REST API: validates user_id
+    @app.post('/users/<user_id>')
+    def update_user(user_id):
+        validate_user_id(user_id)  # Validation here
+        return process_update(user_id)
+
+    # But CLI skips validation
+    def cli_update(user_id):
+        return process_update(user_id)  # No validation!
+  good: |
+    # Shared validation
+    def process_update(user_id):
+        validate_user_id(user_id)  # Always validated
+        # ... actual logic
+
+    # REST API
+    @app.post('/users/<user_id>')
+    def update_user(user_id):
+        return process_update(user_id)
+
+    # CLI
+    def cli_update(user_id):
+        return process_update(user_id)  # Validation inherited
+---
+
+## Observation
+
+Services often have multiple entry points: REST API, CLI, WebSocket, scheduled jobs. Validation logic gets implemented at one entry point (usually REST, where frameworks make it easy) but bypassed at others. Invalid data flows to the core logic, causing unexpected behavior.
+
+## Insight
+
+Entry point diversity is a feature (flexibility), but it creates a validation surface. Each entry point is a potential bypass. Without centralized validation, the defense is only as strong as the most permissive entry point.
+
+## Lesson
+
+Apply defense-in-depth to input validation:
+
+1. **Centralize**: Move validation into the core logic function, not the entry point handler.
+2. **All entry points**: Every path to the core logic must pass through validation — API, CLI, WebSocket, cron, admin UI.
+3. **Explicit validation**: Don't rely on type hints or schema inference; call a validation function explicitly.
+
+Pattern:
+
+```
+REST API → validate() → process()
+CLI      → validate() → process()
+WebSocket → validate() → process()
+```
+
+If validation is expensive (e.g., database lookup), cache the result. If validation differs per entry point, that's a smell — it means the entry points have different semantics. Either merge them or document the difference explicitly.
+
+Test all entry points with the same invalid input set to verify they all reject it consistently.

package/docs/lessons/0026-linter-no-rules-false-enforcement.md

@@ -0,0 +1,54 @@
+---
+id: 26
+title: "Linter with no rules enabled = false enforcement"
+severity: should-fix
+languages: [all]
+scope: [universal]
+category: silent-failures
+pattern:
+  type: semantic
+  description: "Linter installed with zero rules configured reports 0 issues regardless of code quality"
+fix: "Always configure rules explicitly; test that the linter catches a known-bad sample"
+example:
+  bad: |
+    # pylint installed, no .pylintrc
+    $ pylint mymodule.py
+    Your code has been rated at 10.00/10 (previous run: 10.00/10)
+    # No issues reported, but code is full of undefined variables and bad practices
+
+    # .pylintrc exists but all rules disabled
+    [MESSAGES CONTROL]
+    disable=all
+  good: |
+    # .pylintrc with explicit rules
+    [MESSAGES CONTROL]
+    disable=fixme,too-many-arguments,line-too-long
+
+    # Test the linter catches known issues
+    $ cat > test_bad.py << 'EOF'
+    x = undefined_variable
+    EOF
+    $ pylint test_bad.py
+    E0602: Undefined variable 'undefined_variable'
+---
+
+## Observation
+
+Linters installed but misconfigured (no config file, or config with all rules disabled) report perfect scores on any code. Teams believe they have linting enforcement when they have none.
+
+## Insight
+
+Linting is a visibility layer — it surfaces code quality issues. An unconfigured or disabled linter creates false visibility: problems exist but the linter doesn't report them. This is worse than no linting, because teams act on the false signal.
+
+## Lesson
+
+When setting up a linter:
+
+1. **Explicit configuration**: Create a config file (`.pylintrc`, `.eslintrc.json`, etc.) with at least one rule enabled.
+2. **Baseline test**: Create a file with a known-bad pattern (undefined variable, unused import, etc.), run the linter, verify it catches it.
+3. **Disable intentionally**: Start with defaults, then disable rules that conflict with your style (not all rules).
+4. **CI integration**: Run the linter in CI/pre-commit hooks; fail builds on lint errors.
+
+Don't disable large categories of rules unless you have a specific reason. "We don't care about line length" is a reason; "linting is too strict" is not. If the default rules feel too strict, discuss as a team and pick the ones that matter.
+
+Verify linting is working by occasionally committing code that violates an enabled rule and confirming CI catches it.

package/docs/lessons/0027-jsx-silent-prop-drop.md

@@ -0,0 +1,64 @@
+---
+id: 27
+title: "JSX silently drops wrong prop names"
+severity: should-fix
+languages: [javascript, typescript]
+scope: [framework:preact]
+category: silent-failures
+pattern:
+  type: semantic
+  description: "JSX component receives prop with wrong name and silently ignores it"
+fix: "Use TypeScript with strict component prop types; without TS, verify prop names against component signature"
+example:
+  bad: |
+    // Component definition
+    function UserCard({ name, email }) {
+      return <div>{name} - {email}</div>;
+    }
+
+    // Caller: typo in prop name
+    <UserCard name="Alice" emial="alice@example.com" />
+    // Renders as "Alice - undefined" with no error
+  good: |
+    // TypeScript: catches typo at build time
+    interface Props {
+      name: string;
+      email: string;
+    }
+    function UserCard({ name, email }: Props) {
+      return <div>{name} - {email}</div>;
+    }
+
+    // TypeScript error: "emial" is not assignable to type 'Props'
+---
+
+## Observation
+
+JSX silently ignores props that don't match the component's destructuring. A typo in a prop name (e.g., `emial` instead of `email`) renders as an empty or undefined value with no warning. The component silently degrades instead of surfacing the error.
+
+## Insight
+
+JSX is syntactic sugar over function calls. Passing an unknown prop is like passing an unused argument — JavaScript doesn't care. The component receives `{ name, email }` destructured from the props object; any other keys are ignored. Without a type system, there's no way to know a prop was missed.
+
+## Lesson
+
+Guard against silent prop drops:
+
+1. **Use TypeScript**: Define component props as interfaces and use strict mode. TypeScript will catch unknown props at build time.
+2. **Code review**: Without TypeScript, manually verify prop names. List them in a comment or doc.
+3. **PropTypes** (React): Use PropTypes in development to catch missing/wrong props at runtime.
+
+Example with PropTypes:
+
+```javascript
+function UserCard({ name, email }) {
+  return <div>{name} - {email}</div>;
+}
+
+UserCard.propTypes = {
+  name: PropTypes.string.isRequired,
+  email: PropTypes.string.isRequired,
+};
+```
+
+TypeScript is better (caught at build time), but PropTypes is better than nothing. Test with a known-bad sample (e.g., `<UserCard name="Alice" />` missing email) and verify the error is caught.

package/docs/lessons/0028-no-infrastructure-in-client-code.md

@@ -0,0 +1,49 @@
+---
+id: 28
+title: "Never embed infrastructure details in client-side code"
+severity: blocker
+languages: [javascript, typescript]
+scope: [universal]
+category: silent-failures
+pattern:
+  type: syntactic
+  regex: "['\"]https?://\\d+\\.\\d+\\.\\d+\\.\\d+"
+  description: "Hardcoded IP addresses or localhost URLs in client-side code"
+fix: "Use relative URLs, environment variables, or a config endpoint"
+example:
+  bad: |
+    // hardcoded IP in client code
+    const API_URL = 'http://192.168.1.100:8080';
+
+    fetch(`${API_URL}/users`)
+      .then(r => r.json())
+      .then(data => console.log(data));
+  good: |
+    // Use relative URL or environment variable
+    const API_URL = process.env.REACT_APP_API_URL || '/api';
+
+    fetch(`${API_URL}/users`)
+      .then(r => r.json())
+      .then(data => console.log(data));
+---
+
+## Observation
+
+Client-side code containing hardcoded IP addresses, `localhost:port` URLs, or internal hostnames breaks when deployed to different environments. These details change between development, staging, and production, but hardcoding them means shipping different code for each environment.
+
+## Insight
+
+Client-side code is delivered to users' browsers and cannot be changed post-deployment. Infrastructure details (which IP, which port) are deployment decisions, not code decisions. Embedding them couples code to infrastructure and breaks portability.
+
+## Lesson
+
+Never hardcode infrastructure details in client code:
+
+1. **Relative URLs**: Use `fetch('/api/users')` instead of `fetch('http://192.168.1.100:8080/api/users')`. The browser sends requests to the same origin.
+2. **Environment variables**: Use `process.env.REACT_APP_API_URL` (React) or similar, set at build time per environment.
+3. **Config endpoint**: On app startup, fetch config from a well-known endpoint, then use returned URLs.
+4. **DNS names**: Use domain names (`api.example.com`), not IP addresses. IPs change; domains don't.
+
+Verification: Deploy the same compiled artifact to three environments (dev, staging, prod) and verify it connects to the correct backend in each. If you need to rebuild for each environment, you've embedded infrastructure.
+
+This applies equally to API keys — never hardcode them. Use environment variables or secure token exchange.