@soleri/core 9.13.0 → 9.14.4

package/dist/knowledge-packs/starter/api-design/soleri-pack.json

@@ -0,0 +1,9 @@
+{
+  "id": "starter-api-design",
+  "name": "API Design Starter Pack",
+  "version": "1.0.0",
+  "description": "REST conventions, error responses, validation, versioning, auth patterns, pagination — essential API design patterns.",
+  "domains": ["api", "architecture"],
+  "tier": "default",
+  "vault": { "dir": "vault" }
+}

package/dist/knowledge-packs/starter/api-design/vault/patterns.json

@@ -0,0 +1,137 @@
+[
+  {
+    "id": "api-001",
+    "type": "pattern",
+    "domain": "api",
+    "title": "Nouns for Resources, Verbs for Actions",
+    "description": "Use plural nouns for resource endpoints: /users, /orders, /products. Reserve verbs for non-CRUD actions on a resource: POST /users/:id/activate, POST /orders/:id/cancel. Let HTTP methods convey the operation — GET reads, POST creates, PUT replaces, PATCH updates, DELETE removes. Anti-example: GET /getUsers, POST /createOrder, DELETE /deleteUser/:id.",
+    "severity": "warning",
+    "tags": ["api", "rest", "naming"]
+  },
+  {
+    "id": "api-002",
+    "type": "pattern",
+    "domain": "api",
+    "title": "Consistent Error Response Shape (RFC 7807)",
+    "description": "Return errors in a uniform structure following RFC 7807 Problem Details. Every error response should include: type (URI identifying the error class), title (short human-readable summary), status (HTTP status code), detail (specific explanation for this occurrence), instance (URI identifying the specific request). Example:\n{\n  \"type\": \"https://api.example.com/errors/insufficient-funds\",\n  \"title\": \"Insufficient Funds\",\n  \"status\": 422,\n  \"detail\": \"Account balance is $10.00, but the transfer requires $25.00.\",\n  \"instance\": \"/transfers/abc-123\"\n}\nThis makes error handling consistent across all clients — no guessing which field holds the message.",
+    "severity": "warning",
+    "tags": ["api", "error-handling", "rfc7807"]
+  },
+  {
+    "id": "api-003",
+    "type": "rule",
+    "domain": "api",
+    "title": "Validate Input at the Boundary",
+    "description": "Never trust client data. Validate every field at the API boundary before it reaches business logic or the database. Use schema validation (Zod, Joi, JSON Schema) to enforce types, ranges, formats, and required fields. Reject invalid input with a 400 response and a clear list of validation errors. Example response:\n{\n  \"type\": \"https://api.example.com/errors/validation\",\n  \"title\": \"Validation Error\",\n  \"status\": 400,\n  \"detail\": \"Request body failed validation.\",\n  \"errors\": [\n    { \"field\": \"email\", \"message\": \"Must be a valid email address\" },\n    { \"field\": \"age\", \"message\": \"Must be between 0 and 150\" }\n  ]\n}\nValidation at the boundary prevents injection, type confusion, and data corruption downstream.",
+    "severity": "critical",
+    "tags": ["api", "validation", "security"]
+  },
+  {
+    "id": "api-004",
+    "type": "pattern",
+    "domain": "api",
+    "title": "Use HTTP Status Codes Correctly",
+    "description": "Match the status code to the actual outcome. Common mappings: 200 OK — successful read or update. 201 Created — resource created (include Location header). 204 No Content — successful delete or update with no body. 400 Bad Request — malformed or invalid input. 401 Unauthorized — missing or invalid credentials. 403 Forbidden — valid credentials but insufficient permissions. 404 Not Found — resource does not exist. 409 Conflict — state conflict (duplicate email, outdated version). 422 Unprocessable Entity — syntactically valid but semantically wrong. 429 Too Many Requests — rate limit exceeded. Anti-pattern: returning 200 with { \"error\": true } in the body.",
+    "severity": "warning",
+    "tags": ["api", "rest", "http"]
+  },
+  {
+    "id": "api-005",
+    "type": "pattern",
+    "domain": "api",
+    "title": "Cursor-Based Pagination Over Offset",
+    "description": "Prefer cursor-based pagination over offset/limit. Offset pagination breaks when rows are inserted or deleted between pages, and performance degrades on large offsets (the database still scans skipped rows). Cursor pagination uses an opaque token (usually an encoded ID or timestamp) for stable, performant page traversal. Response shape:\n{\n  \"data\": [...],\n  \"pagination\": {\n    \"next_cursor\": \"eyJpZCI6MTAwfQ==\",\n    \"has_more\": true\n  }\n}\nRequest: GET /users?cursor=eyJpZCI6MTAwfQ==&limit=25. Use offset only for simple admin UIs where users need to jump to arbitrary pages.",
+    "severity": "warning",
+    "tags": ["api", "pagination", "performance"]
+  },
+  {
+    "id": "api-006",
+    "type": "pattern",
+    "domain": "api",
+    "title": "Idempotency Keys for POST Operations",
+    "description": "Accept an Idempotency-Key header on POST endpoints to prevent duplicate operations from retries. The server stores the key and its response; if the same key is sent again, return the stored response without re-executing. This is critical for payment, order, and any state-changing endpoints where network retries could cause double-processing. Implementation: client generates a UUID, sends it as Idempotency-Key header. Server checks a key store (Redis/DB) — if found, return cached response; if not, process and store. Keys should expire after 24-48 hours.\nExample header: Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000",
+    "severity": "warning",
+    "tags": ["api", "idempotency", "reliability"]
+  },
+  {
+    "id": "api-007",
+    "type": "pattern",
+    "domain": "api",
+    "title": "Rate Limiting with Standard Headers",
+    "description": "Protect your API with rate limiting and communicate limits via standard headers. Include these headers on every response:\nRateLimit-Limit: 100 (max requests per window)\nRateLimit-Remaining: 42 (requests left in current window)\nRateLimit-Reset: 1620000000 (Unix timestamp when the window resets)\nWhen the limit is exceeded, return 429 Too Many Requests with a Retry-After header (seconds until the client can retry). Use sliding window or token bucket algorithms. Apply different limits per tier (free: 100/min, pro: 1000/min) and per endpoint (auth endpoints should have stricter limits).",
+    "severity": "warning",
+    "tags": ["api", "rate-limiting", "security"]
+  },
+  {
+    "id": "api-008",
+    "type": "pattern",
+    "domain": "api",
+    "title": "API Versioning via URL Prefix",
+    "description": "Version your API using a URL prefix: /v1/users, /v2/users. This is the most explicit and cacheable approach. Alternatives like Accept headers (Accept: application/vnd.api+json;version=2) are harder to test in browsers and less visible in logs. Rules: never break a published version — add fields, don't remove them. Deprecate old versions with a Sunset header and a deprecation notice in the response. Maintain at most 2 active versions. Document the migration path between versions.",
+    "severity": "warning",
+    "tags": ["api", "versioning", "architecture"]
+  },
+  {
+    "id": "api-009",
+    "type": "pattern",
+    "domain": "api",
+    "title": "HATEOAS Links for Discoverability",
+    "description": "Include hypermedia links in responses so clients can discover related actions without hardcoding URLs. Use a _links object with relation types. Example:\n{\n  \"id\": \"usr_123\",\n  \"name\": \"Jane\",\n  \"_links\": {\n    \"self\": { \"href\": \"/v1/users/usr_123\" },\n    \"orders\": { \"href\": \"/v1/users/usr_123/orders\" },\n    \"activate\": { \"href\": \"/v1/users/usr_123/activate\", \"method\": \"POST\" }\n  }\n}\nThis reduces client-server coupling — clients follow links instead of constructing URLs. Especially valuable for public APIs with external consumers.",
+    "severity": "suggestion",
+    "tags": ["api", "rest", "hateoas", "discoverability"]
+  },
+  {
+    "id": "api-010",
+    "type": "pattern",
+    "domain": "api",
+    "title": "ETags and Conditional Requests",
+    "description": "Use ETags for caching and concurrency control. Return an ETag header with a hash of the response content. Clients send If-None-Match on GET requests — return 304 Not Modified if unchanged (saves bandwidth). For updates, clients send If-Match — return 412 Precondition Failed if the resource was modified since it was read (prevents lost updates). Example flow:\nGET /users/123 → 200, ETag: \"abc123\"\nGET /users/123, If-None-Match: \"abc123\" → 304 Not Modified\nPUT /users/123, If-Match: \"abc123\" → 200 (or 412 if stale)\nThis prevents both unnecessary data transfer and write conflicts.",
+    "severity": "suggestion",
+    "tags": ["api", "caching", "concurrency", "etag"]
+  },
+  {
+    "id": "api-011",
+    "type": "pattern",
+    "domain": "api",
+    "title": "Bulk Operations Over N+1 Calls",
+    "description": "Provide batch endpoints for operations that clients commonly perform on multiple resources. Instead of making N individual requests, clients send a single batch request. Example — bulk status update:\nPATCH /v1/orders/batch\n{\n  \"operations\": [\n    { \"id\": \"ord_1\", \"status\": \"shipped\" },\n    { \"id\": \"ord_2\", \"status\": \"shipped\" }\n  ]\n}\nReturn per-item results so partial failures are visible:\n{\n  \"results\": [\n    { \"id\": \"ord_1\", \"status\": \"success\" },\n    { \"id\": \"ord_2\", \"status\": \"error\", \"error\": \"Order not found\" }\n  ]\n}\nUse 207 Multi-Status when results are mixed. Set a reasonable max batch size (100-500 items).",
+    "severity": "suggestion",
+    "tags": ["api", "batch", "performance"]
+  },
+  {
+    "id": "api-012",
+    "type": "rule",
+    "domain": "api",
+    "title": "Short-Lived JWTs with Refresh Tokens",
+    "description": "Use short-lived access tokens (5-15 minutes) paired with long-lived refresh tokens (7-30 days). Access tokens are JWTs sent in the Authorization header — they are stateless and fast to validate. Refresh tokens are opaque, stored server-side, and used only to obtain new access tokens. Never store tokens in localStorage (XSS-vulnerable) — use httpOnly cookies for refresh tokens and in-memory storage for access tokens. Rotate refresh tokens on every use (one-time use). Revoke refresh tokens server-side on logout or security events.",
+    "severity": "critical",
+    "tags": ["api", "auth", "jwt", "security"]
+  },
+  {
+    "id": "api-013",
+    "type": "anti-pattern",
+    "domain": "api",
+    "title": "Exposing Internal IDs and Stack Traces",
+    "description": "Never expose auto-increment database IDs, internal service names, or stack traces in API responses. Sequential IDs leak information about your data volume and allow enumeration attacks. Stack traces reveal implementation details useful for attackers. Use UUIDs or prefixed opaque IDs (usr_abc123, ord_xyz789) for external identifiers. In production, log stack traces server-side but return only a generic error and a correlation ID to the client:\n{\n  \"type\": \"https://api.example.com/errors/internal\",\n  \"title\": \"Internal Server Error\",\n  \"status\": 500,\n  \"detail\": \"An unexpected error occurred.\",\n  \"instance\": \"req_abc123\"\n}",
+    "severity": "critical",
+    "tags": ["api", "security", "error-handling"]
+  },
+  {
+    "id": "api-014",
+    "type": "anti-pattern",
+    "domain": "api",
+    "title": "God Endpoint That Does Everything",
+    "description": "Avoid single endpoints that accept an 'action' field to perform wildly different operations: POST /api { action: 'createUser' } and POST /api { action: 'deleteOrder' }. This makes routing opaque, documentation impossible, and per-endpoint auth/rate-limiting impractical. Each resource and operation should have its own endpoint with clear HTTP method semantics. If you need to orchestrate multiple operations, use a dedicated workflow endpoint (POST /v1/checkout) rather than a generic dispatch.",
+    "severity": "warning",
+    "tags": ["api", "rest", "architecture"]
+  },
+  {
+    "id": "api-015",
+    "type": "pattern",
+    "domain": "api",
+    "title": "Request Correlation IDs for Tracing",
+    "description": "Generate a unique correlation ID for every incoming request and propagate it through all downstream services. Accept a client-provided X-Request-ID header (validate it is a UUID), or generate one if missing. Include it in every log line, error response, and outgoing service call. This makes debugging distributed issues trivial — search by correlation ID to see the full request lifecycle. Return the ID in the response header so clients can reference it in bug reports:\nX-Request-ID: 550e8400-e29b-41d4-a716-446655440000",
+    "severity": "warning",
+    "tags": ["api", "observability", "tracing"]
+  }
+]

package/dist/knowledge-packs/starter/architecture/soleri-pack.json

@@ -0,0 +1,10 @@
+{
+  "id": "starter-architecture",
+  "name": "Architecture Starter Pack",
+  "version": "1.0.0",
+  "description": "Clean architecture, DDD patterns, API design, error handling — foundational architecture patterns and anti-patterns.",
+  "domains": ["architecture"],
+  "vault": {
+    "dir": "vault"
+  }
+}

package/dist/knowledge-packs/starter/architecture/vault/patterns.json

@@ -0,0 +1,137 @@
+[
+  {
+    "id": "arch-001",
+    "type": "pattern",
+    "domain": "architecture",
+    "title": "Dependency Inversion via Interfaces",
+    "description": "High-level modules should not depend on low-level modules. Both should depend on abstractions. Define interfaces for external dependencies (databases, APIs, file systems) and inject implementations. This enables testing and swapping implementations without changing business logic.",
+    "severity": "warning",
+    "tags": ["solid", "dependency-injection", "clean-architecture"]
+  },
+  {
+    "id": "arch-002",
+    "type": "pattern",
+    "domain": "architecture",
+    "title": "Error Boundaries at Layer Edges",
+    "description": "Catch and translate errors at the boundary between architectural layers. Database errors become domain errors. HTTP errors become user-facing messages. Each layer speaks its own error language. Never let implementation details leak through error messages.",
+    "severity": "warning",
+    "tags": ["error-handling", "layers", "boundaries"]
+  },
+  {
+    "id": "arch-003",
+    "type": "pattern",
+    "domain": "architecture",
+    "title": "Command Query Separation",
+    "description": "Functions should either change state (command) or return data (query), never both. Commands return void or a simple status. Queries are side-effect free. This makes code predictable, testable, and easier to reason about.",
+    "severity": "suggestion",
+    "tags": ["cqs", "clean-code", "functional"]
+  },
+  {
+    "id": "arch-004",
+    "type": "pattern",
+    "domain": "architecture",
+    "title": "Idempotent Operations",
+    "description": "Design operations to be safely retryable. Use unique request IDs for deduplication. Make database writes idempotent with UPSERT or conditional INSERT. This is critical for distributed systems where network failures cause retries.",
+    "severity": "warning",
+    "tags": ["idempotency", "distributed-systems", "reliability"]
+  },
+  {
+    "id": "arch-005",
+    "type": "pattern",
+    "domain": "architecture",
+    "title": "Graceful Degradation",
+    "description": "When an external dependency fails, degrade gracefully instead of crashing. Return cached data, empty results, or reduced functionality. Log the failure for monitoring. The system should remain useful even when parts are down.",
+    "severity": "warning",
+    "tags": ["resilience", "fault-tolerance", "reliability"]
+  },
+  {
+    "id": "arch-006",
+    "type": "pattern",
+    "domain": "architecture",
+    "title": "Configuration as Data",
+    "description": "Express variation through configuration, not code branches. Feature flags, policy objects, and declarative config files are easier to audit, test, and change than if/else chains. Logic in config, not code.",
+    "severity": "suggestion",
+    "tags": ["configuration", "data-driven", "clean-code"]
+  },
+  {
+    "id": "arch-007",
+    "type": "pattern",
+    "domain": "architecture",
+    "title": "Reversible Migrations",
+    "description": "Every database migration must have a corresponding rollback. Test both up and down paths. Prefer additive changes (add column, add table) over destructive ones (drop column, rename). Make breaking schema changes in multiple steps: add new → migrate data → remove old.",
+    "severity": "warning",
+    "tags": ["database", "migrations", "schema"]
+  },
+  {
+    "id": "arch-008",
+    "type": "anti-pattern",
+    "domain": "architecture",
+    "title": "God Object",
+    "description": "Avoid classes or modules that know too much or do too much. A 2000-line service class with 30 methods violates single responsibility. Split by cohesion: group related data and behavior together. If a change to feature A requires modifying the same file as feature B, they should be separate modules.",
+    "severity": "warning",
+    "tags": ["solid", "cohesion", "refactoring"]
+  },
+  {
+    "id": "arch-009",
+    "type": "anti-pattern",
+    "domain": "architecture",
+    "title": "Premature Abstraction",
+    "description": "Don't abstract before you have three concrete examples of the same pattern. One-off helpers and single-use base classes add indirection without value. Wait for the pattern to emerge from real usage, then extract. Three similar lines are better than a premature abstraction.",
+    "severity": "suggestion",
+    "tags": ["abstraction", "yagni", "clean-code"]
+  },
+  {
+    "id": "arch-010",
+    "type": "anti-pattern",
+    "domain": "architecture",
+    "title": "Circular Dependencies",
+    "description": "When module A imports B and B imports A, you have a circular dependency. This signals tangled responsibilities and makes code hard to test and refactor. Fix by extracting shared types into a third module, or inverting the dependency with an interface.",
+    "severity": "warning",
+    "tags": ["dependencies", "coupling", "modules"]
+  },
+  {
+    "id": "arch-011",
+    "type": "pattern",
+    "domain": "architecture",
+    "title": "API Versioning Strategy",
+    "description": "Version APIs from day one using URL path (/v1/) or headers. Never break existing consumers. Deprecate old versions with sunset dates. New versions can change behavior; existing versions are frozen. Document breaking changes in changelogs.",
+    "severity": "warning",
+    "tags": ["api-design", "versioning", "backwards-compatibility"]
+  },
+  {
+    "id": "arch-012",
+    "type": "anti-pattern",
+    "domain": "architecture",
+    "title": "Shared Mutable State Without Synchronization",
+    "description": "Accessing shared mutable state from multiple concurrent contexts (threads, async operations, workers) without synchronization leads to race conditions. Use immutable data structures, message passing, or explicit synchronization primitives.",
+    "severity": "critical",
+    "tags": ["concurrency", "race-conditions", "state"]
+  },
+  {
+    "id": "arch-013",
+    "type": "rule",
+    "domain": "architecture",
+    "title": "Validate at System Boundaries Only",
+    "description": "Validate input at the edge of your system (HTTP handlers, CLI parsers, message consumers). Internal functions trust their callers. This avoids redundant validation scattered throughout the codebase and keeps business logic clean.",
+    "severity": "suggestion",
+    "tags": ["validation", "boundaries", "clean-code"]
+  },
+  {
+    "id": "arch-014",
+    "type": "pattern",
+    "domain": "architecture",
+    "title": "Repository Pattern for Data Access",
+    "description": "Encapsulate data access behind a repository interface. The repository exposes domain-oriented methods (findByEmail, listActive) instead of raw queries. This decouples business logic from storage implementation and makes testing trivial with in-memory implementations.",
+    "severity": "suggestion",
+    "tags": ["repository", "data-access", "clean-architecture"]
+  },
+  {
+    "id": "arch-015",
+    "type": "anti-pattern",
+    "domain": "architecture",
+    "title": "Feature Flags as Permanent Conditionals",
+    "description": "Feature flags are temporary. If a flag has been active for more than one release cycle, either remove the old path or make the new behavior permanent. Accumulated flags create combinatorial complexity that is impossible to test exhaustively.",
+    "severity": "suggestion",
+    "tags": ["feature-flags", "technical-debt", "complexity"]
+  }
+]

package/dist/knowledge-packs/starter/design/soleri-pack.json

@@ -0,0 +1,10 @@
+{
+  "id": "starter-design",
+  "name": "Frontend & Design Starter Pack",
+  "version": "1.0.0",
+  "description": "React patterns, accessibility, performance, component composition — essential frontend and UI design patterns.",
+  "domains": ["frontend", "accessibility"],
+  "vault": {
+    "dir": "vault"
+  }
+}

package/dist/knowledge-packs/starter/design/vault/patterns.json

@@ -0,0 +1,137 @@
+[
+  {
+    "id": "fe-001",
+    "type": "pattern",
+    "domain": "frontend",
+    "title": "Composition Over Inheritance in Components",
+    "description": "Build components by composing smaller, focused pieces rather than extending base components. Use children, render props, or slots for flexibility. A Card component with CardHeader, CardBody, CardFooter slots is more reusable than a monolithic Card with 15 props.",
+    "severity": "warning",
+    "tags": ["react", "composition", "components"]
+  },
+  {
+    "id": "fe-002",
+    "type": "pattern",
+    "domain": "frontend",
+    "title": "Controlled Components for Forms",
+    "description": "Prefer controlled components (state-driven) over uncontrolled (DOM-driven) for form inputs. This gives you validation on every keystroke, conditional rendering, and predictable state. Use uncontrolled only for simple, isolated forms where performance is critical.",
+    "severity": "suggestion",
+    "tags": ["react", "forms", "state"]
+  },
+  {
+    "id": "fe-003",
+    "type": "pattern",
+    "domain": "frontend",
+    "title": "Semantic HTML Before ARIA",
+    "description": "Use native HTML elements for their intended purpose before reaching for ARIA attributes. A <button> is better than a <div role='button'>. A <nav> is better than <div aria-label='navigation'>. Native elements get keyboard handling, focus management, and screen reader support for free.",
+    "severity": "warning",
+    "tags": ["accessibility", "html", "aria", "wcag"]
+  },
+  {
+    "id": "fe-004",
+    "type": "pattern",
+    "domain": "frontend",
+    "title": "Error Boundaries for Resilient UI",
+    "description": "Wrap major UI sections in error boundaries so a crash in one component doesn't take down the entire page. Show a meaningful fallback UI with a retry option. Log errors to your monitoring service. Place boundaries at route level and around third-party components.",
+    "severity": "warning",
+    "tags": ["react", "error-handling", "resilience"]
+  },
+  {
+    "id": "fe-005",
+    "type": "pattern",
+    "domain": "frontend",
+    "title": "Lazy Loading for Route-Level Code Splitting",
+    "description": "Use dynamic imports (React.lazy, import()) for route-level components. This reduces initial bundle size and improves first paint. Combine with Suspense for loading states. Only eagerly load the routes users are most likely to visit first.",
+    "severity": "suggestion",
+    "tags": ["performance", "code-splitting", "react"]
+  },
+  {
+    "id": "fe-006",
+    "type": "pattern",
+    "domain": "accessibility",
+    "title": "Focus Management on Navigation",
+    "description": "When the user navigates to a new page or opens a modal, move focus to the appropriate element. After route change, focus the main heading or skip-to-content link. In modals, trap focus within the modal and restore it on close.",
+    "severity": "warning",
+    "tags": ["accessibility", "focus", "keyboard", "wcag"]
+  },
+  {
+    "id": "fe-007",
+    "type": "pattern",
+    "domain": "accessibility",
+    "title": "Color Contrast Minimum 4.5:1",
+    "description": "Ensure text has at least 4.5:1 contrast ratio against its background (WCAG AA). Large text (18px+ bold or 24px+ regular) needs 3:1 minimum. Use semantic design tokens that guarantee compliant pairs. Test with a contrast checker tool.",
+    "severity": "warning",
+    "tags": ["accessibility", "contrast", "wcag", "design-tokens"]
+  },
+  {
+    "id": "fe-008",
+    "type": "anti-pattern",
+    "domain": "frontend",
+    "title": "Prop Drilling Through Many Layers",
+    "description": "Passing props through 3+ intermediate components that don't use them is prop drilling. It creates tight coupling and makes refactoring painful. Use React Context for truly global state, or component composition (passing children) to reduce nesting depth.",
+    "severity": "suggestion",
+    "tags": ["react", "state", "composition"]
+  },
+  {
+    "id": "fe-009",
+    "type": "anti-pattern",
+    "domain": "frontend",
+    "title": "Inline Styles Over Design Tokens",
+    "description": "Don't use inline styles or raw hex colors in components. They bypass the design system, create inconsistency, and make theming impossible. Use semantic tokens (bg-surface, text-primary) that resolve to values through the token system.",
+    "severity": "warning",
+    "tags": ["design-tokens", "css", "consistency"]
+  },
+  {
+    "id": "fe-010",
+    "type": "anti-pattern",
+    "domain": "frontend",
+    "title": "useEffect for Derived State",
+    "description": "Don't use useEffect to sync state that can be computed from other state. If fullName = firstName + lastName, compute it during render, not in an effect. Effects for derived state cause extra re-renders and race conditions. Use useMemo for expensive computations.",
+    "severity": "warning",
+    "tags": ["react", "hooks", "performance"]
+  },
+  {
+    "id": "fe-011",
+    "type": "pattern",
+    "domain": "frontend",
+    "title": "Optimistic UI Updates",
+    "description": "Update the UI immediately on user action before the server confirms. Show the expected outcome with a subtle loading indicator. Roll back on error with a toast notification. This makes the app feel instant even on slow connections.",
+    "severity": "suggestion",
+    "tags": ["ux", "performance", "state"]
+  },
+  {
+    "id": "fe-012",
+    "type": "anti-pattern",
+    "domain": "accessibility",
+    "title": "Click Handlers on Non-Interactive Elements",
+    "description": "Don't add onClick to divs or spans without also adding role='button', tabIndex=0, and keyboard event handlers. Screen readers and keyboard users can't interact with these elements. Use a <button> element instead — it handles all of this natively.",
+    "severity": "warning",
+    "tags": ["accessibility", "keyboard", "html", "wcag"]
+  },
+  {
+    "id": "fe-013",
+    "type": "pattern",
+    "domain": "frontend",
+    "title": "Skeleton Loading States",
+    "description": "Show skeleton placeholders that match the layout of the content being loaded. This reduces perceived load time and prevents layout shift. Use CSS animations for shimmer effects. Skeletons are better than spinners for content-heavy pages.",
+    "severity": "suggestion",
+    "tags": ["ux", "performance", "loading"]
+  },
+  {
+    "id": "fe-014",
+    "type": "rule",
+    "domain": "accessibility",
+    "title": "Every Interactive Element Must Be Keyboard Accessible",
+    "description": "Every element that can be clicked must also be reachable and operable via keyboard. This means focusable (tabindex or native element), visible focus indicator (focus-visible ring), and keyboard activation (Enter/Space for buttons, Enter for links).",
+    "severity": "critical",
+    "tags": ["accessibility", "keyboard", "wcag"]
+  },
+  {
+    "id": "fe-015",
+    "type": "anti-pattern",
+    "domain": "frontend",
+    "title": "Boolean Prop Explosion",
+    "description": "Avoid components with many boolean props like isPrimary, isOutlined, isSmall, isDisabled. Use a variant prop with explicit values instead: variant='primary' | 'outlined' | 'ghost'. This prevents impossible states (isPrimary && isOutlined) and is self-documenting.",
+    "severity": "suggestion",
+    "tags": ["react", "api-design", "components"]
+  }
+]

package/dist/knowledge-packs/starter/nodejs/soleri-pack.json

@@ -0,0 +1,9 @@
+{
+  "id": "starter-nodejs",
+  "name": "Node.js Starter Pack",
+  "version": "1.0.0",
+  "description": "Error handling, async patterns, streams, security, module system — essential Node.js patterns for production servers.",
+  "domains": ["nodejs", "backend"],
+  "tier": "default",
+  "vault": { "dir": "vault" }
+}

package/dist/knowledge-packs/starter/nodejs/vault/patterns.json

@@ -0,0 +1,137 @@
+[
+  {
+    "id": "node-001",
+    "type": "rule",
+    "domain": "nodejs",
+    "title": "Always Handle Promise Rejections",
+    "severity": "critical",
+    "description": "Unhandled promise rejections terminate the Node.js process (since v15). Every promise chain needs a .catch(), and every async function call needs try/catch or a .catch() on the returned promise. Set a global safety net, but don't rely on it:\n\nprocess.on('unhandledRejection', (reason, promise) => {\n  logger.error('Unhandled rejection', { reason });\n  process.exit(1);\n});\n\nThis global handler is a last resort — fix the root cause by handling rejections at the call site.",
+    "tags": ["nodejs", "error-handling", "async"]
+  },
+  {
+    "id": "node-002",
+    "type": "pattern",
+    "domain": "nodejs",
+    "title": "Use AbortController for Cancellable Async Operations",
+    "severity": "warning",
+    "description": "AbortController is the standard way to cancel async work — fetch requests, timers, streams, and custom operations. Pass an AbortSignal to anything long-running so callers can cancel it:\n\nasync function fetchWithTimeout(url, timeoutMs = 5000) {\n  const controller = new AbortController();\n  const timeout = setTimeout(() => controller.abort(), timeoutMs);\n  try {\n    const res = await fetch(url, { signal: controller.signal });\n    return await res.json();\n  } finally {\n    clearTimeout(timeout);\n  }\n}\n\nNode.js built-ins like fs, http, and timers all support AbortSignal natively.",
+    "tags": ["nodejs", "async", "cancellation"]
+  },
+  {
+    "id": "node-003",
+    "type": "pattern",
+    "domain": "nodejs",
+    "title": "Streams Over Buffering for Large Data",
+    "severity": "warning",
+    "description": "Never read an entire file or HTTP response into memory when you can stream it. Buffering large data causes memory spikes, GC pressure, and OOM crashes under load. Use pipeline() from node:stream/promises for safe stream composition with automatic error handling and cleanup:\n\nimport { pipeline } from 'node:stream/promises';\nimport { createReadStream, createWriteStream } from 'node:fs';\nimport { createGzip } from 'node:zlib';\n\nawait pipeline(\n  createReadStream('input.log'),\n  createGzip(),\n  createWriteStream('input.log.gz')\n);\n\npipeline() destroys all streams on error — no leaked file descriptors.",
+    "tags": ["nodejs", "streams", "performance", "memory"]
+  },
+  {
+    "id": "node-004",
+    "type": "pattern",
+    "domain": "nodejs",
+    "title": "Graceful Shutdown on SIGTERM and SIGINT",
+    "severity": "warning",
+    "description": "Production servers must shut down cleanly — stop accepting new connections, finish in-flight requests, close database pools, then exit. Without this, deploys cause dropped requests and data corruption:\n\nfunction gracefulShutdown(server, db) {\n  let shuttingDown = false;\n  const shutdown = async (signal) => {\n    if (shuttingDown) return;\n    shuttingDown = true;\n    console.log(`${signal} received, shutting down...`);\n    server.close();\n    await db.end();\n    process.exit(0);\n  };\n  process.on('SIGTERM', () => shutdown('SIGTERM'));\n  process.on('SIGINT', () => shutdown('SIGINT'));\n}\n\nSet a hard timeout (e.g., 30s) to force exit if cleanup stalls.",
+    "tags": ["nodejs", "deployment", "reliability", "signals"]
+  },
+  {
+    "id": "node-005",
+    "type": "pattern",
+    "domain": "nodejs",
+    "title": "Validate Environment Variables at Startup",
+    "severity": "warning",
+    "description": "Fail fast if required environment variables are missing. Don't let the process start and fail 10 minutes later when it first tries to connect to a database. Validate at the top of your entry point:\n\nfunction requireEnv(name) {\n  const value = process.env[name];\n  if (!value) {\n    console.error(`Missing required env var: ${name}`);\n    process.exit(1);\n  }\n  return value;\n}\n\nconst config = {\n  dbUrl: requireEnv('DATABASE_URL'),\n  port: Number(process.env.PORT) || 3000,\n  nodeEnv: process.env.NODE_ENV || 'development',\n};\n\nExport a frozen config object — never read process.env directly in business logic.",
+    "tags": ["nodejs", "configuration", "validation", "fail-fast"]
+  },
+  {
+    "id": "node-006",
+    "type": "anti-pattern",
+    "domain": "nodejs",
+    "title": "Synchronous File Operations in Request Handlers",
+    "severity": "critical",
+    "description": "Never use readFileSync, writeFileSync, or any *Sync method in request handlers. They block the entire event loop — no other request can be processed until the I/O completes. One slow disk read blocks every connected client:\n\n// BAD — blocks the event loop\napp.get('/config', (req, res) => {\n  const data = fs.readFileSync('config.json', 'utf8');\n  res.json(JSON.parse(data));\n});\n\n// GOOD — non-blocking\napp.get('/config', async (req, res) => {\n  const data = await fs.promises.readFile('config.json', 'utf8');\n  res.json(JSON.parse(data));\n});\n\nSync methods are acceptable at startup for loading config before the server starts listening.",
+    "tags": ["nodejs", "performance", "event-loop", "async"]
+  },
+  {
+    "id": "node-007",
+    "type": "pattern",
+    "domain": "nodejs",
+    "title": "Custom Error Subclasses for Domain Errors",
+    "severity": "suggestion",
+    "description": "Create typed error classes instead of throwing generic Error objects. This enables precise catch handling, proper HTTP status mapping, and structured logging:\n\nclass AppError extends Error {\n  constructor(message, code, statusCode = 500) {\n    super(message);\n    this.name = this.constructor.name;\n    this.code = code;\n    this.statusCode = statusCode;\n  }\n}\n\nclass NotFoundError extends AppError {\n  constructor(resource, id) {\n    super(`${resource} ${id} not found`, 'NOT_FOUND', 404);\n  }\n}\n\nclass ValidationError extends AppError {\n  constructor(message, fields) {\n    super(message, 'VALIDATION_ERROR', 400);\n    this.fields = fields;\n  }\n}\n\nCatch by class: if (err instanceof NotFoundError) — not by message string matching.",
+    "tags": ["nodejs", "error-handling", "architecture"]
+  },
+  {
+    "id": "node-008",
+    "type": "pattern",
+    "domain": "nodejs",
+    "title": "Use node:test and node:assert for Built-in Testing",
+    "severity": "suggestion",
+    "description": "Node.js ships a capable test runner since v18. Zero dependencies, native TypeScript support (--experimental-strip-types), and fast startup. Use it before reaching for Jest or Vitest:\n\nimport { describe, it, mock } from 'node:test';\nimport assert from 'node:assert/strict';\n\ndescribe('UserService', () => {\n  it('creates a user with hashed password', async () => {\n    const hash = mock.fn(() => 'hashed');\n    const service = new UserService({ hash });\n    const user = await service.create('alice', 'pass');\n    assert.equal(user.name, 'alice');\n    assert.equal(hash.mock.calls.length, 1);\n  });\n});\n\nRun with: node --test --test-reporter spec",
+    "tags": ["nodejs", "testing", "built-in"]
+  },
+  {
+    "id": "node-009",
+    "type": "rule",
+    "domain": "nodejs",
+    "title": "Prefer ESM, Understand CJS Interop",
+    "severity": "warning",
+    "description": "Use ES modules (import/export) as the default for new projects. Set \"type\": \"module\" in package.json. ESM gives you static analysis, tree-shaking, and top-level await.\n\nKey interop rules:\n- ESM can import CJS: import pkg from 'cjs-package' (gets default export)\n- CJS cannot require() ESM — use dynamic import(): const mod = await import('esm-package')\n- Named exports from CJS may need destructuring from default: import pkg from 'cjs-lib'; const { method } = pkg;\n- __dirname and __filename don't exist in ESM — use: import.meta.dirname and import.meta.filename (Node 21+), or path.dirname(fileURLToPath(import.meta.url)) for older versions",
+    "tags": ["nodejs", "modules", "esm", "cjs"]
+  },
+  {
+    "id": "node-010",
+    "type": "anti-pattern",
+    "domain": "nodejs",
+    "title": "User Input in Child Process Commands",
+    "severity": "critical",
+    "description": "Never interpolate user input into shell commands. This is command injection — the #1 server-side vulnerability:\n\n// DANGEROUS — command injection\nconst { exec } = require('child_process');\nexec(`git log --author=\"${userInput}\"`);\n// userInput = '\"; rm -rf / #' → catastrophic\n\n// SAFE — use array form, bypasses the shell entirely\nimport { execFile } from 'node:child_process';\nexecFile('git', ['log', `--author=${userInput}`]);\n\nRules: use execFile/spawn (not exec/execSync), never set shell: true with user data, validate and sanitize all inputs. If you need a shell, use a whitelist of allowed values.",
+    "tags": ["nodejs", "security", "child-process", "injection"]
+  },
+  {
+    "id": "node-011",
+    "type": "pattern",
+    "domain": "nodejs",
+    "title": "Crypto Best Practices: randomUUID, scrypt, timingSafeEqual",
+    "severity": "warning",
+    "description": "Use Node.js built-in crypto correctly — don't install third-party packages for basics:\n\nimport { randomUUID, scryptSync, timingSafeEqual, randomBytes } from 'node:crypto';\n\n// Generate IDs\nconst id = randomUUID(); // v4 UUID, cryptographically random\n\n// Hash passwords (scrypt is memory-hard, resistant to GPU attacks)\nconst salt = randomBytes(16);\nconst hash = scryptSync(password, salt, 64);\n\n// Compare secrets (constant-time, prevents timing attacks)\nconst isValid = timingSafeEqual(\n  Buffer.from(providedToken),\n  Buffer.from(storedToken)\n);\n\nNever use MD5/SHA for passwords. Never compare secrets with === (timing leak). Never use Math.random() for security-sensitive values.",
+    "tags": ["nodejs", "security", "crypto", "authentication"]
+  },
+  {
+    "id": "node-012",
+    "type": "rule",
+    "domain": "nodejs",
+    "title": "Always Handle EventEmitter 'error' Events",
+    "severity": "critical",
+    "description": "An EventEmitter that emits 'error' with no listener crashes the process with an uncaught exception. This applies to streams, HTTP servers, database connections, and any custom emitter:\n\n// This WILL crash if the file doesn't exist\nconst stream = fs.createReadStream('missing.txt');\n// Fix: always attach an error handler\nstream.on('error', (err) => {\n  logger.error('Stream failed', { error: err.message });\n});\n\n// For custom emitters, consider a default error handler:\nclass MyService extends EventEmitter {\n  constructor() {\n    super();\n    this.on('error', (err) => {\n      // Prevents crash if consumer forgets to listen\n      console.error('Unhandled service error:', err);\n    });\n  }\n}\n\nRule: if you create it or receive it, listen for 'error' on it.",
+    "tags": ["nodejs", "error-handling", "events", "streams"]
+  },
+  {
+    "id": "node-013",
+    "type": "pattern",
+    "domain": "nodejs",
+    "title": "Structured Logging Over Console.log",
+    "severity": "suggestion",
+    "description": "Use structured JSON logging instead of console.log in production. Structured logs are parseable by log aggregators (Datadog, CloudWatch, ELK) and support filtering, alerting, and correlation:\n\n// Minimal structured logger (no dependencies)\nconst log = (level, message, meta = {}) => {\n  const entry = JSON.stringify({\n    timestamp: new Date().toISOString(),\n    level,\n    message,\n    ...meta,\n  });\n  process.stdout.write(entry + '\\n');\n};\n\nlog('info', 'Request handled', {\n  method: 'GET',\n  path: '/users',\n  duration: 42,\n  statusCode: 200,\n});\n\nAlways include: timestamp, level, message, request ID. Never log secrets, tokens, or passwords.",
+    "tags": ["nodejs", "logging", "observability", "production"]
+  },
+  {
+    "id": "node-014",
+    "type": "anti-pattern",
+    "domain": "nodejs",
+    "title": "Swallowing Errors with Empty Catch Blocks",
+    "severity": "warning",
+    "description": "An empty catch block hides failures and makes debugging impossible. Every catch must do something meaningful — log, rethrow, return a default, or translate the error:\n\n// BAD — silent failure, impossible to debug\ntry {\n  await sendEmail(user);\n} catch (e) {}\n\n// GOOD — log and continue (if email is non-critical)\ntry {\n  await sendEmail(user);\n} catch (err) {\n  logger.warn('Email send failed', { userId: user.id, error: err.message });\n}\n\n// GOOD — rethrow with context\ntry {\n  await db.query(sql);\n} catch (err) {\n  throw new AppError(`Query failed: ${err.message}`, 'DB_ERROR', 500);\n}\n\nIf you genuinely don't care about the error, add a comment explaining why.",
+    "tags": ["nodejs", "error-handling", "debugging"]
+  },
+  {
+    "id": "node-015",
+    "type": "pattern",
+    "domain": "nodejs",
+    "title": "Use AsyncLocalStorage for Request Context",
+    "severity": "suggestion",
+    "description": "AsyncLocalStorage provides implicit context propagation through async call chains — no need to pass requestId, userId, or tracing data through every function parameter:\n\nimport { AsyncLocalStorage } from 'node:async_hooks';\n\nconst requestContext = new AsyncLocalStorage();\n\n// Middleware: set context per request\napp.use((req, res, next) => {\n  const store = { requestId: randomUUID(), userId: req.user?.id };\n  requestContext.run(store, next);\n});\n\n// Anywhere in the call stack:\nfunction getRequestId() {\n  return requestContext.getStore()?.requestId;\n}\n\n// Logger automatically includes request ID\nconst log = (level, msg, meta) => {\n  const ctx = requestContext.getStore() || {};\n  console.log(JSON.stringify({ ...ctx, level, msg, ...meta }));\n};\n\nThis is how APM tools and logging frameworks implement automatic trace correlation.",
+    "tags": ["nodejs", "async", "context", "observability"]
+  }
+]

package/dist/knowledge-packs/starter/react/soleri-pack.json

@@ -0,0 +1,9 @@
+{
+  "id": "starter-react",
+  "name": "React Starter Pack",
+  "version": "1.0.0",
+  "description": "Hook rules, component patterns, state management, performance optimization, error boundaries — essential React patterns.",
+  "domains": ["react", "frontend"],
+  "tier": "default",
+  "vault": { "dir": "vault" }
+}