engrm 0.1.0 → 0.2.1

package/package.json

@@ -1,28 +1,57 @@
 {
   "name": "engrm",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Cross-device, team-shared memory layer for AI coding agents",
   "type": "module",
-  "main": "src/server.ts",
+  "main": "dist/server.js",
   "bin": {
-    "engrm": "src/cli.ts"
+    "engrm": "dist/cli.js"
   },
+  "files": [
+    "bin/",
+    "dist/",
+    "packs/",
+    "LICENSE",
+    "LICENSE-SENTINEL"
+  ],
   "scripts": {
     "start": "bun run src/server.ts",
     "init": "bun run src/cli.ts init",
-    "test": "bun test"
+    "test": "bun test",
+    "build": "bun run bin/build.mjs",
+    "prepublishOnly": "bun run build"
   },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "engrm",
+    "ai-memory",
+    "claude-code",
+    "mcp",
+    "coding-agent",
+    "context-injection",
+    "sentinel",
+    "code-audit",
+    "cross-device",
+    "team-memory",
+    "developer-tools"
+  ],
   "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.2.74",
     "@modelcontextprotocol/sdk": "^1.12.1",
     "@xenova/transformers": "^2.17.2",
+    "better-sqlite3": "^12.6.2",
     "sqlite-vec": "^0.1.7-alpha.2"
   },
   "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
     "@types/bun": "^1.2.19",
     "typescript": "^5.8.3"
   },
+  "homepage": "https://engrm.dev",
   "license": "FSL-1.1-ALv2",
-  "author": "Unimpossible Consultants",
+  "author": "Engrm <hello@engrm.dev> (https://engrm.dev)",
   "repository": {
     "type": "git",
     "url": "https://github.com/unimpossible/candengo-mem"

package/packs/api-best-practices.json

@@ -0,0 +1,182 @@
+{
+  "name": "api-best-practices",
+  "description": "REST API design patterns, error handling, and operational best practices",
+  "version": "1.0.0",
+  "observations": [
+    {
+      "type": "pattern",
+      "title": "Use appropriate HTTP status codes — not everything is 200",
+      "narrative": "Status codes convey meaning to clients. 200 for success, 201 for created, 204 for no content, 400 for bad request, 401 for unauthorized, 403 for forbidden, 404 for not found, 409 for conflict, 422 for validation errors, 429 for rate limited, 500 for server error.",
+      "facts": ["201 Created for POST that creates a resource", "204 No Content for successful DELETE", "422 Unprocessable Entity for validation failures", "429 Too Many Requests with Retry-After header"],
+      "concepts": ["http-status-codes", "rest-api", "error-responses"]
+    },
+    {
+      "type": "pattern",
+      "title": "Version your API from day one — /v1/ prefix or header",
+      "narrative": "API versioning prevents breaking changes for existing clients. URL prefix (/v1/) is most common and easily cacheable. Header versioning is cleaner but harder to test.",
+      "facts": ["URL versioning: /v1/users, /v2/users", "Header versioning: Accept: application/vnd.api+json;version=1", "Never make breaking changes to an existing version", "Deprecate old versions with sunset headers"],
+      "concepts": ["api-versioning", "backwards-compatibility", "breaking-changes"]
+    },
+    {
+      "type": "pattern",
+      "title": "Consistent error response format across all endpoints",
+      "narrative": "Every error response should follow the same structure. Clients should be able to parse errors without knowing which endpoint returned them.",
+      "facts": ["Include: status, error code (machine-readable), message (human-readable)", "Optional: details array for field-level validation errors", "Example: {\"error\": {\"code\": \"INVALID_EMAIL\", \"message\": \"...\", \"details\": [...]}}", "Document all possible error codes"],
+      "concepts": ["error-format", "api-design", "error-codes"]
+    },
+    {
+      "type": "pattern",
+      "title": "Paginate list endpoints — never return unbounded results",
+      "narrative": "List endpoints must support pagination. Cursor-based pagination is more reliable than offset-based for real-time data.",
+      "facts": ["Cursor pagination: ?after=<cursor>&limit=20", "Offset pagination: ?page=2&per_page=20 (breaks with insertions)", "Return total count and next page cursor/link", "Default limit of 20-50, max limit of 100"],
+      "concepts": ["pagination", "cursor-pagination", "list-endpoints"]
+    },
+    {
+      "type": "pattern",
+      "title": "Use plural nouns for resource endpoints — /users not /user",
+      "narrative": "RESTful URLs represent collections. Use plural nouns (/users, /orders) and let HTTP methods express the action (GET, POST, PUT, DELETE).",
+      "facts": ["GET /users — list users", "POST /users — create user", "GET /users/123 — get specific user", "Don't use verbs: /getUsers, /createUser is wrong"],
+      "concepts": ["rest-naming", "url-design", "resource-naming"]
+    },
+    {
+      "type": "pattern",
+      "title": "Implement idempotent operations — same request, same result",
+      "narrative": "GET, PUT, DELETE should be idempotent (multiple identical requests produce the same result). For POST, use Idempotency-Key headers to prevent duplicate creation.",
+      "facts": ["GET: naturally idempotent (read-only)", "PUT: replace entire resource, naturally idempotent", "DELETE: deleting twice should return 204/404, not error", "POST: use Idempotency-Key header for payment/order creation"],
+      "concepts": ["idempotency", "idempotency-key", "safe-retries"]
+    },
+    {
+      "type": "pattern",
+      "title": "Rate limit all endpoints — use token bucket or sliding window",
+      "narrative": "Rate limiting protects against abuse, DoS, and runaway clients. Return 429 with Retry-After header. Different limits for authenticated vs anonymous users.",
+      "facts": ["Token bucket: smooth, allows short bursts", "Sliding window: strict, predictable limits", "Return X-RateLimit-Limit, X-RateLimit-Remaining headers", "Higher limits for authenticated users"],
+      "concepts": ["rate-limiting", "throttling", "api-protection"]
+    },
+    {
+      "type": "pattern",
+      "title": "Validate all input at the boundary — use schema validation",
+      "narrative": "Validate request bodies, query parameters, and path parameters at the API boundary. Use schema validation libraries (Zod, Joi, JSON Schema) for consistent enforcement.",
+      "facts": ["Validate types, ranges, formats, required fields", "Return 422 with field-level error details", "Reject unknown fields to prevent mass assignment", "Schema doubles as documentation"],
+      "concepts": ["input-validation", "schema-validation", "zod", "api-security"]
+    },
+    {
+      "type": "pattern",
+      "title": "Use ETags and If-None-Match for HTTP caching",
+      "narrative": "ETags enable conditional requests. The server returns ETag headers; clients send If-None-Match on subsequent requests. Server returns 304 Not Modified if unchanged.",
+      "facts": ["ETag: hash or version of the response body", "Client sends If-None-Match: <etag> on next request", "Server returns 304 if unchanged (saves bandwidth)", "Also useful for optimistic concurrency (If-Match for PUT)"],
+      "concepts": ["etag", "http-caching", "conditional-requests", "304"]
+    },
+    {
+      "type": "pattern",
+      "title": "Use PATCH for partial updates — PUT replaces the entire resource",
+      "narrative": "PUT semantics require sending the complete resource. PATCH updates only the fields provided. Use JSON Merge Patch (RFC 7396) for simple cases.",
+      "facts": ["PUT: client sends complete resource, server replaces it", "PATCH: client sends only changed fields", "JSON Merge Patch: {\"name\": \"new\"} updates only name", "Return the updated resource in the response"],
+      "concepts": ["patch", "partial-update", "put-vs-patch"]
+    },
+    {
+      "type": "pattern",
+      "title": "Structured logging with request ID for traceability",
+      "narrative": "Every request should get a unique ID (X-Request-Id). Log it with all related operations. This enables tracing a request across services.",
+      "facts": ["Generate UUID request ID in middleware", "Return it in response headers", "Include in all log entries for that request", "Propagate to downstream service calls"],
+      "concepts": ["request-id", "structured-logging", "tracing", "observability"]
+    },
+    {
+      "type": "pattern",
+      "title": "Health check endpoint: GET /health with dependency status",
+      "narrative": "Load balancers and monitoring need a health endpoint. Return 200 when healthy, 503 when degraded. Include dependency status (DB, cache, queues).",
+      "facts": ["GET /health — lightweight, no auth required", "Include: status, version, uptime, dependencies", "Check database connectivity, cache, external services", "Separate liveness (/healthz) from readiness (/readyz)"],
+      "concepts": ["health-check", "monitoring", "load-balancer", "kubernetes"]
+    },
+    {
+      "type": "pattern",
+      "title": "Use bearer tokens in Authorization header — not query params",
+      "narrative": "Authentication tokens belong in the Authorization header (Bearer <token>). Query parameter tokens are logged in access logs and browser history.",
+      "facts": ["Authorization: Bearer <token>", "Query param tokens leak in logs, referrers, bookmarks", "API keys in X-Api-Key header for server-to-server", "Never send tokens in GET request body"],
+      "concepts": ["authentication", "bearer-token", "api-key", "security"]
+    },
+    {
+      "type": "pattern",
+      "title": "Implement request/response compression — gzip or brotli",
+      "narrative": "Compress API responses to reduce bandwidth. Most frameworks support this via middleware. Check Accept-Encoding header and set Content-Encoding.",
+      "facts": ["Brotli: better compression ratio, slower to compress", "Gzip: widely supported, fast enough for dynamic content", "Don't compress already-compressed formats (images, video)", "Set Vary: Accept-Encoding for proper caching"],
+      "concepts": ["compression", "gzip", "brotli", "performance"]
+    },
+    {
+      "type": "pattern",
+      "title": "Soft delete resources — don't hard delete by default",
+      "narrative": "Instead of DELETE removing data permanently, set a deleted_at timestamp. This allows recovery, audit trails, and referential integrity.",
+      "facts": ["Add deleted_at column (null = active)", "Filter deleted records in all queries by default", "Provide purge endpoint for permanent deletion (admin only)", "Cascade soft deletes to dependent resources"],
+      "concepts": ["soft-delete", "data-retention", "audit-trail"]
+    },
+    {
+      "type": "pattern",
+      "title": "Document APIs with OpenAPI/Swagger — generated from code",
+      "narrative": "API documentation must be accurate and up-to-date. Generate OpenAPI specs from code annotations or schema definitions. Serve interactive docs at /docs.",
+      "facts": ["OpenAPI 3.1 is the current standard", "Generate from code (not hand-written) to stay in sync", "Swagger UI or Redoc for interactive documentation", "Include request/response examples"],
+      "concepts": ["openapi", "swagger", "api-documentation"]
+    },
+    {
+      "type": "pattern",
+      "title": "Use webhooks for async notifications — don't make clients poll",
+      "narrative": "For events that happen asynchronously (payment completed, build finished), push notifications via webhooks instead of requiring clients to poll.",
+      "facts": ["Sign webhook payloads with HMAC for verification", "Retry with exponential backoff on delivery failure", "Include event type and timestamp in payload", "Provide webhook testing/replay in dashboard"],
+      "concepts": ["webhooks", "async-events", "push-notifications"]
+    },
+    {
+      "type": "pattern",
+      "title": "Graceful degradation: circuit breaker for downstream services",
+      "narrative": "When a downstream service fails, don't let every request timeout. Use a circuit breaker pattern that fails fast after detecting failures, then periodically retries.",
+      "facts": ["Closed (normal) → Open (fast fail) → Half-Open (test)", "Track failure rate in sliding window", "Return cached/default response when circuit is open", "Libraries: opossum (Node.js), resilience4j (Java)"],
+      "concepts": ["circuit-breaker", "resilience", "graceful-degradation"]
+    },
+    {
+      "type": "discovery",
+      "title": "GraphQL vs REST: use GraphQL for complex, nested data needs",
+      "narrative": "GraphQL excels when clients need flexible queries over related data. REST is simpler for CRUD operations. Choose based on your data access patterns.",
+      "facts": ["GraphQL: single endpoint, client specifies needed fields", "REST: multiple endpoints, server decides response shape", "GraphQL N+1 problem: use DataLoader for batching", "REST is better for simple CRUD and caching"],
+      "concepts": ["graphql", "rest", "api-design", "data-fetching"]
+    },
+    {
+      "type": "pattern",
+      "title": "Implement request timeouts and connection limits",
+      "narrative": "Every outgoing HTTP call needs a timeout. Every server needs connection limits. Without these, slow clients or downstream services can exhaust resources.",
+      "facts": ["Set connect timeout (5s) and read timeout (30s) separately", "Limit concurrent connections per client", "Use keepalive connections for repeated calls to same host", "Set server-side request timeout (e.g., 30s) as safety net"],
+      "concepts": ["timeouts", "connection-limits", "resource-management"]
+    },
+    {
+      "type": "pattern",
+      "title": "Return created resource on POST with Location header",
+      "narrative": "POST endpoints that create resources should return 201 with the created resource in the body and a Location header pointing to the new resource URL.",
+      "facts": ["201 Created with body containing the new resource", "Location: /v1/users/123 header for the new resource URL", "Include server-generated fields (id, created_at)", "Saves client from making a follow-up GET"],
+      "concepts": ["post-response", "201-created", "location-header"]
+    },
+    {
+      "type": "pattern",
+      "title": "Use correlation IDs across microservices for distributed tracing",
+      "narrative": "In microservice architectures, propagate a correlation ID from the entry point through all service calls. This enables end-to-end request tracing.",
+      "facts": ["Generate at API gateway or first service", "Propagate via X-Correlation-Id or traceparent header", "Include in all log entries across services", "Tools: OpenTelemetry, Jaeger, Zipkin"],
+      "concepts": ["correlation-id", "distributed-tracing", "microservices", "opentelemetry"]
+    },
+    {
+      "type": "pattern",
+      "title": "Handle N+1 queries in API endpoints — batch database calls",
+      "narrative": "When returning a list of resources with related data, load all relations in one query instead of one query per item. This is the most common API performance issue.",
+      "facts": ["Use JOIN or WHERE IN (...) for batch loading", "ORMs have eager loading: include/with/joinedload", "DataLoader pattern batches within a request cycle", "N+1 turns 1 query into 101 queries for 100 items"],
+      "concepts": ["n-plus-one", "batch-loading", "query-optimization", "orm"]
+    },
+    {
+      "type": "pattern",
+      "title": "Use Content-Type negotiation — support JSON at minimum",
+      "narrative": "Always set Content-Type on responses. Check Accept header on requests to return the right format. Return 406 Not Acceptable if you can't serve the requested format.",
+      "facts": ["application/json is the default for REST APIs", "Check Accept header for content negotiation", "Return Content-Type: application/json on all JSON responses", "406 Not Acceptable if format is unsupported"],
+      "concepts": ["content-negotiation", "content-type", "accept-header"]
+    },
+    {
+      "type": "pattern",
+      "title": "Implement API key rotation without downtime",
+      "narrative": "Allow multiple active API keys per account. Clients generate a new key, update their config, then revoke the old key. Never force immediate key invalidation.",
+      "facts": ["Support multiple concurrent API keys", "Provide key creation and revocation endpoints", "Set expiry dates on keys for automatic rotation", "Log key usage to detect which keys are active"],
+      "concepts": ["api-key-rotation", "key-management", "zero-downtime"]
+    }
+  ]
+}

package/packs/nextjs-patterns.json

@@ -0,0 +1,68 @@
+{
+  "name": "nextjs-patterns",
+  "description": "Next.js App Router patterns, data fetching, and deployment tips",
+  "version": "1.0.0",
+  "stacks": ["nextjs", "react"],
+  "observations": [
+    {
+      "type": "pattern",
+      "title": "Default to Server Components — add 'use client' only when needed",
+      "narrative": "In the App Router, components are Server Components by default. Only add 'use client' for interactivity (hooks, event handlers, browser APIs). Keep the client boundary as low in the tree as possible.",
+      "concepts": ["nextjs", "server-components", "app-router"]
+    },
+    {
+      "type": "pattern",
+      "title": "Fetch data in Server Components, not useEffect",
+      "narrative": "Server Components can be async — fetch data directly with await. No loading spinners, no client-side waterfalls. The HTML arrives fully rendered.",
+      "concepts": ["nextjs", "data-fetching", "server-components"]
+    },
+    {
+      "type": "bugfix",
+      "title": "Next.js caching can serve stale data in production",
+      "narrative": "Next.js aggressively caches fetch() results and route segments. Use revalidatePath/revalidateTag after mutations, or set { cache: 'no-store' } for real-time data.",
+      "concepts": ["nextjs", "caching", "revalidation", "stale-data"]
+    },
+    {
+      "type": "pattern",
+      "title": "Use route groups (parentheses) for layout organization",
+      "narrative": "Folders wrapped in parentheses like (marketing) and (dashboard) create route groups — they organize code and share layouts without affecting the URL path.",
+      "concepts": ["nextjs", "route-groups", "app-router", "layouts"]
+    },
+    {
+      "type": "pattern",
+      "title": "Server Actions for form mutations",
+      "narrative": "Use 'use server' functions for form handling. They run on the server, can access the DB directly, and work without JavaScript. Pair with useFormState for loading/error states.",
+      "concepts": ["nextjs", "server-actions", "forms", "mutations"]
+    },
+    {
+      "type": "discovery",
+      "title": "Parallel routes (@slot) for complex layouts",
+      "narrative": "Parallel routes using @folder convention let you render multiple pages in the same layout simultaneously. Useful for dashboards with independent loading states.",
+      "concepts": ["nextjs", "parallel-routes", "layouts"]
+    },
+    {
+      "type": "pattern",
+      "title": "Use loading.tsx for instant loading states",
+      "narrative": "Place a loading.tsx file in any route directory for automatic Suspense-wrapped loading UI. It shows immediately while the page component fetches data.",
+      "concepts": ["nextjs", "loading", "suspense", "ux"]
+    },
+    {
+      "type": "bugfix",
+      "title": "Dynamic route params are always strings",
+      "narrative": "Route params like [id] are always strings, even if they look like numbers. Always parseInt() or validate before using as numeric IDs in database queries.",
+      "concepts": ["nextjs", "dynamic-routes", "params", "validation"]
+    },
+    {
+      "type": "pattern",
+      "title": "Middleware for auth, redirects, and headers",
+      "narrative": "middleware.ts runs at the edge before every request. Use it for auth checks, locale detection, and response headers. Keep it fast — no heavy computation or DB calls.",
+      "concepts": ["nextjs", "middleware", "auth", "edge"]
+    },
+    {
+      "type": "pattern",
+      "title": "Use next/image for automatic image optimization",
+      "narrative": "The Image component automatically resizes, converts to WebP/AVIF, and lazy-loads images. Always specify width/height or use fill for responsive images to prevent layout shift.",
+      "concepts": ["nextjs", "image", "optimization", "performance"]
+    }
+  ]
+}

package/packs/node-security.json

@@ -0,0 +1,68 @@
+{
+  "name": "node-security",
+  "description": "Node.js and JavaScript security patterns and common vulnerabilities",
+  "version": "1.0.0",
+  "stacks": ["javascript", "bun", "typescript"],
+  "observations": [
+    {
+      "type": "pattern",
+      "title": "Always validate and sanitize user input at boundaries",
+      "narrative": "Never trust input from HTTP requests, WebSocket messages, or CLI arguments. Use Zod, Joi, or similar to validate shape and types before processing.",
+      "concepts": ["security", "input-validation", "xss", "injection"]
+    },
+    {
+      "type": "bugfix",
+      "title": "Prototype pollution via object spread and Object.assign",
+      "narrative": "Merging user-controlled objects with Object.assign or spread can overwrite __proto__. Use Object.create(null) for lookup objects, or validate keys before merging.",
+      "concepts": ["security", "prototype-pollution", "javascript"]
+    },
+    {
+      "type": "pattern",
+      "title": "Use parameterized queries — never interpolate SQL",
+      "narrative": "Template literals in SQL queries enable SQL injection. Always use parameterized queries: db.query('SELECT * FROM users WHERE id = ?', [id]).",
+      "concepts": ["security", "sql-injection", "database", "parameterized"]
+    },
+    {
+      "type": "pattern",
+      "title": "Store secrets in environment variables, never in code",
+      "narrative": "API keys, database passwords, and tokens must come from env vars or a secret manager. Add .env to .gitignore. Use dotenv or platform-native secret injection.",
+      "concepts": ["security", "secrets", "environment-variables"]
+    },
+    {
+      "type": "pattern",
+      "title": "Set security headers: CSP, HSTS, X-Frame-Options",
+      "narrative": "Configure Content-Security-Policy, Strict-Transport-Security, X-Content-Type-Options, and X-Frame-Options on all HTTP responses. Use helmet middleware in Express.",
+      "concepts": ["security", "headers", "csp", "hsts"]
+    },
+    {
+      "type": "bugfix",
+      "title": "SSRF risk from user-supplied URLs in server fetch",
+      "narrative": "If your server fetches URLs from user input, attackers can reach internal services (169.254.169.254, localhost). Validate URLs against an allowlist of domains and block private IP ranges.",
+      "concepts": ["security", "ssrf", "fetch", "url-validation"]
+    },
+    {
+      "type": "pattern",
+      "title": "Use bcrypt or argon2 for password hashing",
+      "narrative": "Never store passwords with SHA-256 or MD5 — they're too fast. Use bcrypt (cost factor 10+) or argon2id. These are deliberately slow and resistant to GPU attacks.",
+      "concepts": ["security", "passwords", "hashing", "bcrypt"]
+    },
+    {
+      "type": "pattern",
+      "title": "Rate limit authentication endpoints",
+      "narrative": "Apply strict rate limiting (e.g., 5 attempts per minute per IP) to login, registration, and password reset endpoints. Use sliding window counters, not simple token buckets.",
+      "concepts": ["security", "rate-limiting", "brute-force", "authentication"]
+    },
+    {
+      "type": "bugfix",
+      "title": "Path traversal in file operations",
+      "narrative": "User-controlled file paths like '../../../etc/passwd' can escape intended directories. Always resolve paths with path.resolve() and verify the result starts with your allowed directory.",
+      "concepts": ["security", "path-traversal", "file-access"]
+    },
+    {
+      "type": "pattern",
+      "title": "Use crypto.timingSafeEqual for secret comparison",
+      "narrative": "Comparing secrets with === is vulnerable to timing attacks. Use crypto.timingSafeEqual(Buffer.from(a), Buffer.from(b)) for constant-time comparison of tokens and signatures.",
+      "concepts": ["security", "timing-attack", "crypto", "comparison"]
+    }
+  ]
+}

package/packs/python-django.json

@@ -0,0 +1,68 @@
+{
+  "name": "python-django",
+  "description": "Python and Django patterns, pitfalls, and best practices",
+  "version": "1.0.0",
+  "stacks": ["python", "django"],
+  "observations": [
+    {
+      "type": "pattern",
+      "title": "Use dataclasses or Pydantic for structured data",
+      "narrative": "Prefer @dataclass or Pydantic BaseModel over plain dicts for structured data. You get type hints, validation, and IDE support instead of stringly-typed key access.",
+      "concepts": ["python", "dataclass", "pydantic", "typing"]
+    },
+    {
+      "type": "bugfix",
+      "title": "Mutable default arguments are shared across calls",
+      "narrative": "def f(items=[]): is a classic Python bug — the list is shared across all calls. Use def f(items=None): items = items or [] instead.",
+      "concepts": ["python", "mutable-default", "gotcha"]
+    },
+    {
+      "type": "pattern",
+      "title": "Django select_related and prefetch_related prevent N+1",
+      "narrative": "Always use .select_related() for ForeignKey and .prefetch_related() for ManyToMany/reverse FK when accessing related objects in loops. Without them, each access fires a separate query.",
+      "concepts": ["django", "orm", "n+1", "performance"]
+    },
+    {
+      "type": "pattern",
+      "title": "Use Django F() expressions for atomic field updates",
+      "narrative": "Model.objects.filter(pk=id).update(count=F('count') + 1) is atomic and avoids race conditions. Direct Python arithmetic (obj.count += 1; obj.save()) is not atomic.",
+      "concepts": ["django", "orm", "f-expression", "concurrency"]
+    },
+    {
+      "type": "discovery",
+      "title": "Python match/case for structural pattern matching",
+      "narrative": "Python 3.10+ match/case supports destructuring dicts, objects, and sequences. match response.status_code: case 200: ... is cleaner than if/elif chains for multi-branch logic.",
+      "concepts": ["python", "match-case", "pattern-matching"]
+    },
+    {
+      "type": "pattern",
+      "title": "Use context managers for resource cleanup",
+      "narrative": "Always use 'with' statements for files, DB connections, locks. Write custom context managers with @contextmanager for any acquire/release pattern.",
+      "concepts": ["python", "context-manager", "resource-management"]
+    },
+    {
+      "type": "bugfix",
+      "title": "Django timezone-aware datetime handling",
+      "narrative": "Use django.utils.timezone.now() not datetime.now(). Naive datetimes cause comparison bugs and warnings. Set USE_TZ=True in settings.",
+      "concepts": ["django", "timezone", "datetime"]
+    },
+    {
+      "type": "pattern",
+      "title": "Type hints with Protocol for duck typing",
+      "narrative": "Use typing.Protocol for structural (duck) typing instead of ABC. Protocols don't require inheritance — any class with matching methods satisfies the protocol.",
+      "concepts": ["python", "protocol", "duck-typing", "typing"]
+    },
+    {
+      "type": "pattern",
+      "title": "Django signals considered harmful for critical logic",
+      "narrative": "Avoid Django signals (post_save, pre_delete) for critical business logic. They run silently, are hard to debug, and create implicit coupling. Call service functions explicitly.",
+      "concepts": ["django", "signals", "architecture"]
+    },
+    {
+      "type": "pattern",
+      "title": "Use __slots__ for memory-efficient value objects",
+      "narrative": "Add __slots__ = ('x', 'y') to classes with many instances. Eliminates per-instance __dict__, reducing memory by 40-50%. Tradeoff: no dynamic attributes.",
+      "concepts": ["python", "slots", "memory", "optimization"]
+    }
+  ]
+}