@ai-cortex/daemon 0.1.0

package/brain/entries/git-merge-conflict.md

@@ -0,0 +1,88 @@
+---
+id: git-merge-conflict
+title: "Git merge conflict resolution"
+language: general
+error_types: ["CONFLICT", "merge conflict", "Automatic merge failed"]
+tags: [debugging, git, merge, version-control]
+---
+
+## Problem
+
+Git reports `CONFLICT` during merge, rebase, or pull. Automatic merge failed because both branches modified the same lines.
+
+## Understanding Conflict Markers
+
+```
+<<<<<<< HEAD
+your changes on the current branch
+=======
+incoming changes from the other branch
+>>>>>>> feature-branch
+```
+
+Everything between `<<<<<<< HEAD` and `=======` is your version. Everything between `=======` and `>>>>>>>` is theirs.
+
+## Resolution Steps
+
+### 1. See which files conflict
+
+```bash
+git status
+```
+
+Files marked `both modified` need manual resolution.
+
+### 2. Edit the files
+
+Open each conflicted file, remove the markers, and keep the correct code. This may mean keeping one side, the other, or a combination.
+
+### 3. Mark as resolved and commit
+
+```bash
+git add <resolved-file>
+git commit
+```
+
+## Shortcut: Accept One Side Entirely
+
+```bash
+# Keep your version for a specific file
+git checkout --ours path/to/file
+
+# Keep their version for a specific file
+git checkout --theirs path/to/file
+```
+
+For an entire merge:
+
+```bash
+git merge -X ours feature-branch   # prefer current branch
+git merge -X theirs feature-branch  # prefer incoming branch
+```
+
+## Abort If Needed
+
+```bash
+git merge --abort    # undo a merge in progress
+git rebase --abort   # undo a rebase in progress
+```
+
+This restores the repository to the state before the merge/rebase started.
+
+## Squash Alternative
+
+If the branch has many small conflicting commits, squash merge avoids per-commit conflicts:
+
+```bash
+git merge --squash feature-branch
+```
+
+This applies all changes as a single uncommitted changeset that you resolve once.
+
+### Quick Checklist
+
+- `git status` to find conflicted files
+- Edit files to remove conflict markers
+- `git add` resolved files, then `git commit`
+- Use `--ours`/`--theirs` for bulk resolution
+- `git merge --abort` to back out safely

package/brain/entries/node-esm-import.md

@@ -0,0 +1,71 @@
+---
+id: node-esm-import
+title: "Node.js ESM import resolution"
+language: javascript
+error_types: [ERR_MODULE_NOT_FOUND, "Cannot find module"]
+tags: [debugging, imports, node, esm]
+---
+
+## Problem
+
+Node.js throws `ERR_MODULE_NOT_FOUND` or `Cannot find module` when using ES module imports. This happens because ESM has stricter resolution rules than CommonJS.
+
+## Root Causes & Fixes
+
+### 1. Missing file extensions in relative imports
+
+ESM requires explicit file extensions. Node will not auto-resolve `.js` or `.ts`:
+
+```javascript
+// WRONG
+import { helper } from './utils';
+
+// CORRECT
+import { helper } from './utils.js';
+```
+
+In TypeScript projects, use `.js` extensions even for `.ts` source files — TypeScript does not rewrite import paths and Node resolves the compiled `.js` output.
+
+### 2. package.json missing `"type": "module"`
+
+Without this field, Node treats `.js` files as CommonJS:
+
+```json
+{
+  "type": "module"
+}
+```
+
+Alternatively, use `.mjs` extension for ES module files without changing package.json.
+
+### 3. TypeScript config
+
+Set these in `tsconfig.json` for ESM output:
+
+```json
+{
+  "compilerOptions": {
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext"
+  }
+}
+```
+
+`"module": "ESNext"` with `"moduleResolution": "bundler"` also works if you use a bundler, but for direct Node execution, `NodeNext` is correct.
+
+### 4. Importing CommonJS packages from ESM
+
+Some packages only export CommonJS. Use the default import:
+
+```javascript
+// If named imports fail:
+import pkg from 'some-cjs-package';
+const { namedExport } = pkg;
+```
+
+### Quick Checklist
+
+- `package.json` has `"type": "module"`
+- All relative imports include `.js` extension
+- `tsconfig.json` uses `NodeNext` module resolution
+- CJS dependencies use default import pattern

package/brain/entries/npm-peer-deps.md

@@ -0,0 +1,93 @@
+---
+id: npm-peer-deps
+title: "npm peer dependency conflicts"
+language: javascript
+error_types: ["ERESOLVE", "peer dep", "Could not resolve dependency"]
+tags: [debugging, npm, dependencies, node]
+---
+
+## Problem
+
+`npm install` fails with `ERESOLVE could not resolve dependency` because two packages require incompatible versions of the same peer dependency.
+
+## Understand the Conflict
+
+```bash
+npm ls <conflicting-package>
+```
+
+This shows the dependency tree and which packages require which versions.
+
+## Quick Fixes
+
+### 1. `--legacy-peer-deps` (safest workaround)
+
+```bash
+npm install --legacy-peer-deps
+```
+
+Tells npm to ignore peer dependency conflicts entirely, using the npm v6 behavior. Does not force install — just skips the strict resolution.
+
+### 2. `--force` (more aggressive)
+
+```bash
+npm install --force
+```
+
+Forces installation even with conflicts. Can produce a broken `node_modules` if versions are truly incompatible at runtime.
+
+### 3. Make it persistent
+
+Add to `.npmrc` so the whole team gets the same behavior:
+
+```ini
+legacy-peer-deps=true
+```
+
+## Proper Fixes
+
+### 1. Update packages to compatible versions
+
+```bash
+npm outdated
+npm update <package>
+```
+
+Often the conflict goes away when you update to the latest versions of both packages.
+
+### 2. Use `overrides` (npm 8.3+)
+
+Force a specific version of the conflicting dependency in `package.json`:
+
+```json
+{
+  "overrides": {
+    "react": "^18.0.0"
+  }
+}
+```
+
+This tells npm to use React 18 everywhere, even if some packages declare a peer dep on React 17.
+
+### 3. Use `resolutions` (yarn)
+
+```json
+{
+  "resolutions": {
+    "react": "^18.0.0"
+  }
+}
+```
+
+## When to Fix vs Force
+
+- **Fix** when the conflicting packages have updates that resolve the issue
+- **Force** when a package declares an overly strict peer dep but actually works with your version (common with React)
+- **Override** when you have tested that the shared dependency works and want a permanent solution
+
+### Quick Checklist
+
+- `npm ls <package>` to see the conflict tree
+- Try `--legacy-peer-deps` first
+- Check if updating packages resolves the conflict
+- Use `overrides` in package.json for a permanent fix

package/brain/entries/python-import-circular.md

@@ -0,0 +1,112 @@
+---
+id: python-import-circular
+title: "Python circular import resolution"
+language: python
+error_types: [ImportError, "cannot import name", "partially initialized module"]
+tags: [debugging, python, imports, circular]
+---
+
+## Problem
+
+Python raises `ImportError: cannot import name 'X' from partially initialized module` or similar errors caused by two modules importing each other.
+
+## Why It Happens
+
+```python
+# module_a.py
+from module_b import B
+
+class A:
+    pass
+
+# module_b.py
+from module_a import A  # Fails! module_a is still loading
+
+class B:
+    pass
+```
+
+When Python imports `module_a`, it starts executing it. The first line imports `module_b`, which tries to import `A` from `module_a` — but `module_a` has not finished executing yet, so `A` does not exist.
+
+## Fixes
+
+### 1. Move imports inside functions (lazy import)
+
+```python
+# module_b.py
+class B:
+    def use_a(self):
+        from module_a import A  # Import at usage time, not module load
+        return A()
+```
+
+This breaks the cycle because the import only runs when the function is called, by which time both modules are fully loaded.
+
+### 2. Use `TYPE_CHECKING` guard for type annotations
+
+```python
+from __future__ import annotations
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from module_a import A  # Only imported by type checkers, not at runtime
+
+class B:
+    def use_a(self) -> 'A':
+        ...
+```
+
+`TYPE_CHECKING` is `False` at runtime, so the import never executes. The `from __future__ import annotations` makes all annotations strings by default, avoiding runtime evaluation.
+
+### 3. Extract shared types into a separate module
+
+```python
+# types.py (no circular imports — only defines types)
+class ABase:
+    pass
+
+class BBase:
+    pass
+
+# module_a.py
+from types import ABase, BBase
+
+# module_b.py
+from types import ABase, BBase
+```
+
+Moving shared interfaces or base classes to a third module breaks the cycle.
+
+### 4. Use `importlib` as an escape hatch
+
+```python
+import importlib
+
+def get_a():
+    module_a = importlib.import_module('module_a')
+    return module_a.A
+```
+
+This is the most flexible but least readable option. Use only when the other approaches do not fit.
+
+### 5. Restructure the modules
+
+Often circular imports indicate that two modules are too tightly coupled. Consider:
+
+- Merging them into a single module
+- Extracting the shared dependency into a third module
+- Using dependency injection instead of direct imports
+
+## Detection
+
+Circular imports typically show up as:
+- `ImportError: cannot import name 'X'`
+- `AttributeError: partially initialized module`
+- The error only appears when importing in a specific order
+
+### Quick Checklist
+
+- Move imports inside functions for quick fixes
+- Use `TYPE_CHECKING` guard for type-only imports
+- Extract shared types into a separate module
+- Consider restructuring if circles are deep

package/brain/entries/python-import-resolution.md

@@ -0,0 +1,83 @@
+---
+id: python-import-resolution
+title: "Python import resolution"
+language: python
+error_types: [ImportError, ModuleNotFoundError]
+tags: [debugging, imports, python, packages]
+---
+
+## Problem
+
+Python raises `ImportError` or `ModuleNotFoundError` when importing modules, even though the file exists on disk.
+
+## Root Causes & Fixes
+
+### 1. Module not on `sys.path`
+
+Python only searches directories listed in `sys.path`. Check it:
+
+```python
+import sys
+print(sys.path)
+```
+
+Common fix — run as a module from the project root:
+
+```bash
+python -m mypackage.mymodule
+```
+
+This adds the current directory to `sys.path` automatically.
+
+### 2. Missing `__init__.py`
+
+For Python to treat a directory as a package, it needs an `__init__.py` file (can be empty):
+
+```
+myproject/
+  mypackage/
+    __init__.py
+    module_a.py
+    module_b.py
+```
+
+### 3. Relative vs absolute imports
+
+Inside a package, use relative imports:
+
+```python
+# Inside mypackage/module_b.py
+from .module_a import some_function   # relative
+from mypackage.module_a import some_function  # absolute
+```
+
+Relative imports only work when running as a package (`python -m`), not as a script (`python module_b.py`).
+
+### 4. Local package not installed
+
+For a local package to be importable from anywhere, install it in development mode:
+
+```bash
+pip install -e .
+```
+
+This requires a `pyproject.toml` or `setup.py` at the project root.
+
+### 5. Wrong Python interpreter
+
+Verify you are using the expected Python:
+
+```bash
+which python
+python --version
+pip list | grep mypackage
+```
+
+Virtual environments frequently cause confusion — make sure the venv is activated before running.
+
+### Quick Checklist
+
+- `__init__.py` exists in every package directory
+- Running with `python -m` from project root
+- Package installed with `pip install -e .` for development
+- Correct Python interpreter is active (`which python`)

package/brain/entries/python-venv-activate.md

@@ -0,0 +1,98 @@
+---
+id: python-venv-activate
+title: "Python virtual environment activation"
+language: python
+error_types: ["ModuleNotFoundError", "command not found: python", "No module named pip"]
+tags: [debugging, python, venv, environment]
+---
+
+## Problem
+
+Python virtual environment is not activating, or the wrong Python/pip is being used after activation. Packages install globally instead of in the venv.
+
+## Activation Commands
+
+### Linux / macOS
+
+```bash
+source venv/bin/activate
+```
+
+### Windows (PowerShell)
+
+```powershell
+.\venv\Scripts\Activate.ps1
+```
+
+### Windows (cmd)
+
+```cmd
+venv\Scripts\activate.bat
+```
+
+After activation your prompt should show `(venv)` prefix.
+
+## Verify Correct Python
+
+```bash
+which python       # Linux/macOS
+where python       # Windows
+python --version
+pip list           # Should show only venv packages
+```
+
+If `which python` does not point to `venv/bin/python`, the venv is not active.
+
+## Common Issues
+
+### 1. Deactivate first if switching venvs
+
+```bash
+deactivate
+source other-venv/bin/activate
+```
+
+### 2. PowerShell execution policy blocks activation
+
+```powershell
+Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
+```
+
+### 3. Venv is corrupted or wrong Python version
+
+Delete and recreate:
+
+```bash
+rm -rf venv
+python3.11 -m venv venv   # Use specific Python version
+source venv/bin/activate
+pip install -r requirements.txt
+```
+
+### 4. IDE not using the venv
+
+In VS Code, open the Command Palette and select `Python: Select Interpreter`, then choose the interpreter inside your `venv/` directory.
+
+### 5. `pip` installs globally
+
+Always check that pip belongs to the venv:
+
+```bash
+which pip
+# Should be: /path/to/project/venv/bin/pip
+```
+
+If not, activate the venv or use:
+
+```bash
+python -m pip install <package>
+```
+
+This always uses the pip associated with the active `python`.
+
+### Quick Checklist
+
+- `source venv/bin/activate` (Linux/macOS) or `.\venv\Scripts\Activate.ps1` (Windows)
+- `which python` should point to the venv
+- Recreate venv if corrupted: `python -m venv venv`
+- Use `python -m pip` to guarantee correct pip

package/brain/entries/react-stale-closure.md

@@ -0,0 +1,76 @@
+---
+id: react-stale-closure
+title: "React stale closure in hooks"
+language: javascript
+error_types: ["stale state", "useEffect stale closure", "useState not updating"]
+tags: [debugging, react, hooks, closures]
+---
+
+## Problem
+
+A `useEffect`, `useCallback`, or event handler reads a state variable but always sees the old value instead of the current one. This is a stale closure — the function captured a snapshot of state at render time.
+
+## How It Happens
+
+```jsx
+const [count, setCount] = useState(0);
+
+useEffect(() => {
+  const id = setInterval(() => {
+    console.log(count); // Always logs 0!
+  }, 1000);
+  return () => clearInterval(id);
+}, []); // Empty deps = captures initial count forever
+```
+
+The effect closes over `count` at its initial value. Because the dependency array is empty, it never re-runs to capture the updated value.
+
+## Fixes
+
+### 1. Add the variable to the dependency array
+
+```jsx
+useEffect(() => {
+  const id = setInterval(() => {
+    console.log(count); // Now current
+  }, 1000);
+  return () => clearInterval(id);
+}, [count]); // Re-runs when count changes
+```
+
+### 2. Use functional state updates
+
+When you need the latest state but don't want to re-run the effect:
+
+```jsx
+useEffect(() => {
+  const id = setInterval(() => {
+    setCount((prev) => prev + 1); // Always has latest value
+  }, 1000);
+  return () => clearInterval(id);
+}, []); // Safe — no stale closure
+```
+
+### 3. Use a ref for read-only access
+
+```jsx
+const countRef = useRef(count);
+countRef.current = count; // Sync on every render
+
+useEffect(() => {
+  const id = setInterval(() => {
+    console.log(countRef.current); // Always current
+  }, 1000);
+  return () => clearInterval(id);
+}, []);
+```
+
+### ESLint `exhaustive-deps` Rule
+
+Enable `react-hooks/exhaustive-deps` in your ESLint config. It warns when a dependency is missing from the array. Most stale closure bugs are caught by this rule.
+
+### Quick Checklist
+
+- Every variable used inside `useEffect`/`useCallback` is in the dependency array
+- Use functional updates (`setX(prev => ...)`) when you need latest state without adding a dependency
+- Use refs for values that change but should not trigger re-runs