@shahmilsaari/memory-core 1.0.20 → 1.0.25

package/README.md

@@ -1,8 +1,10 @@
 # memory-core
 
-**Every AI coding agent in your project, following your rules. Automatically.**
+**Your architecture rules, in every AI coding agent. Automatically.**
 
-You decide the architecture. memory-core remembers it. Every AI tool — Copilot, Cursor, Claude Code, Windsurf, and 10 more — reads those rules before writing a single line of code.
+AI agents like Copilot, Cursor, Claude Code, and Windsurf are powerful — but they start fresh every session. They don't know you're using Clean Architecture. They don't know controllers shouldn't call the database. They don't remember why you made that decision six months ago.
+
+memory-core fixes that. You save your architecture rules once. Every AI tool reads them before writing code. Violations get caught before they reach your repo.
 
 Website: https://memory-core.shahmilsaari.my/
 
@@ -10,33 +12,51 @@ Website: https://memory-core.shahmilsaari.my/
 npx @shahmilsaari/memory-core init
 ```
 
-Fully local or cloud — your choice. **v0.2.16**
+Fully local or cloud AI — your choice.
 
 ---
 
-## What does it actually do?
+## How it works
+
+memory-core has three jobs:
+
+**1. Remember** — Store your architecture decisions, rules, and patterns in a local PostgreSQL database with AI-powered search. When you decide "no direct DB calls from controllers", you save that rule with a reason. It's stored forever.
+
+**2. Distribute** — Generate instruction files for 14 AI agents (Cursor, Claude Code, Copilot, Windsurf, etc.) from your stored rules. Every agent reads your rules before it writes code.
 
-Without memory-core, every AI agent starts fresh. It doesn't know you're using Clean Architecture. It doesn't know controllers shouldn't call the database. It doesn't know why you made that decision six months ago.
+**3. Enforce** — Three-layer rule checking catches violations automatically:
+- **Deterministic** — string matching against known bad patterns (instant, no AI needed)
+- **Structural** — import graph analysis to catch architectural boundary violations
+- **AI semantic** — LLM reads the actual code diff against your rules
+
+You can run enforcement in watch mode (checks as you type), as a pre-commit hook (checks before each commit), or in CI (checks on every PR).
+
+---
 
-With memory-core:
+## What's new in this version
 
-1. You run `init` once — it verifies your PostgreSQL and Ollama connections, picks your model, lets you choose which agents to generate files for, and installs a pre-commit hook
-2. Those agents read the files and follow your rules — automatically
-3. Watch mode catches violations as you type, not just at commit time
-4. When you commit, the hook checks your code before the commit goes through (advisory by default — logs violations but never blocks)
+- **AI auto-fix** — When watch mode detects a violation, it can rewrite the file automatically and save the fix as a new rule
+- **Dry-run mode** — Run the full check pipeline without blocking commits: `check --dry-run`
+- **Schema alignment rules** — Define TypeScript↔Go struct pairs; catch field drift automatically: `schema add --ts --go`
+- **Bypass tracking** — Every `MEMORY_CORE_SKIP_HOOK=1` bypass is counted; re-prompted if no reason given
+- **Model switcher in dashboard** — Change provider and model from the UI without restarting
+- **Token usage display** — See AI call counts and token usage; Ollama shows "LOCAL (FREE)"
+- **Actions panel** — Trigger Sync Agents, Check All, and Tune Rules directly from the dashboard
 
 ---
 
 ## Before you start
 
-You need three things installed:
+You need three things:
 
 | What | Why | Install |
 |---|---|---|
 | PostgreSQL 14+ | Stores your rules and decisions | See below |
-| pgvector | Makes search smart (finds similar rules, not just exact matches) | See below |
+| pgvector | Enables AI-powered rule search | See below |
 | Ollama | Runs AI locally — no API key needed | See below |
 
+Cloud providers (OpenAI, Anthropic, MiniMax) are also supported if you prefer not to run Ollama locally.
+
 ---
 
 ## Install
@@ -61,14 +81,14 @@ sudo systemctl start postgresql
 
 ### pgvector
 
-pgvector adds AI-powered search to PostgreSQL.
+pgvector adds AI-powered similarity search to PostgreSQL, so memory-core can find rules related to your query even when you don't use the exact words.
 
-**macOS + PostgreSQL 17+** (easiest)
+**macOS + PostgreSQL 17+**
 ```bash
 brew install pgvector
 ```
 
-**macOS + PostgreSQL 16** (brew's pgvector targets 17+, so build from source)
+**macOS + PostgreSQL 16** (brew targets 17+, so build from source)
 ```bash
 xcode-select --install
 git clone --branch v0.8.0 https://github.com/pgvector/pgvector.git /tmp/pgvector
@@ -82,7 +102,7 @@ make install PG_CONFIG=/opt/homebrew/opt/postgresql@16/bin/pg_config
 sudo apt install postgresql-16-pgvector   # replace 16 with your version
 ```
 
-Check it worked:
+Verify:
 ```bash
 psql -U $(whoami) -c "SELECT * FROM pg_available_extensions WHERE name = 'vector';"
 ```
@@ -91,7 +111,7 @@ psql -U $(whoami) -c "SELECT * FROM pg_available_extensions WHERE name = 'vector
 
 ### Ollama
 
-Ollama runs AI models on your machine. Two models are needed — one for search, one for code checking.
+Ollama runs AI models on your machine. Two models are used: one for search (embeddings) and one for code checking.
 
 **macOS**
 ```bash
@@ -107,10 +127,10 @@ ollama serve &
 
 **Windows** — [download from ollama.com](https://ollama.com/download)
 
-Pull the embedding model. The code-checking model is chosen during `init`:
+Pull the required models:
 ```bash
-ollama pull nomic-embed-text   # required for search
-ollama pull llama3.2           # or whichever model you plan to use
+ollama pull nomic-embed-text   # required for search (always Ollama)
+ollama pull llama3.2           # or whichever model you plan to use for code checking
 ```
 
 ---
@@ -177,45 +197,42 @@ That's it. Every AI agent in your project now has your rules.
 
 ---
 
-## Commands
+## Day-to-day workflow
 
-For the full CLI reference, examples, and command behavior notes, see [COMMANDS.md](./COMMANDS.md).
+```bash
+# Made an architectural decision? Save it.
+npx @shahmilsaari/memory-core remember "Controllers must never call the database directly" \
+  --type rule --reason "Keeps HTTP concerns out of application logic"
 
-New setup-management commands:
-- `memory-core status` — show project name, provider/model, agents, hook state, generated files, and health checks
-- `memory-core auto-sync` — show or change automatic agent file regeneration (`on`, `off`, or `status`)
-- `memory-core uninstall` — remove memory-core from the current project; use `reset` when you only need to regenerate files
-- `memory-core provider set <provider>` — switch code-checking provider without rerunning `init`
-- `memory-core model set <model>` — update chat or embedding model from the CLI
-- `memory-core model doctor` — verify database, Ollama, model installation, and cloud API key presence
-- `memory-core graph build|list|show|diff` — build, inspect, and compare dependency graph snapshots
-- `memory-core graph migrate` — create/update graph snapshot schema in PostgreSQL
-- `memory-core graph doctor` — verify graph backend health (PostgreSQL + file fallback)
-- `memory-core dashboard` — open the local Svelte command center with live WebSocket updates
+# Watch mode — catch violations the moment you save a file
+npx @shahmilsaari/memory-core watch
 
-## User Documentation
+# AI auto-fix — let the AI rewrite violations automatically
+npx @shahmilsaari/memory-core watch --auto-fix
 
-The public docs focus on how to install, use, configure, reset, and uninstall memory-core:
+# See the dashboard — live violations, model status, token usage, actions
+npx @shahmilsaari/memory-core dashboard
 
-- Website: https://memory-core.shahmilsaari.my/
-- Docs: https://memory-core.shahmilsaari.my/docs/
-- Quick start and installation: `website/docs/intro.md`, `website/docs/installation.md`
-- Daily usage: `website/docs/workflow.md`
-- CLI reference: `website/docs/commands.md`
-- Dashboard and model setup: `website/docs/dashboard.md`, `website/docs/models.md`
-- Reset and uninstall behavior: `website/docs/cleanup.md`
-- Architecture migration notes: `docs/migration-phase6-cutover.md`
+# Manual check before a commit
+npx @shahmilsaari/memory-core check --staged
 
-The static homepage remains `index.html` at `/`. Public docs are plain static HTML generated from the markdown files in `website/docs/` and served under `/docs/`.
+# Dry run — see what would be flagged without blocking
+npx @shahmilsaari/memory-core check --staged --dry-run
 
-```bash
-npm run site:start   # build and preview the full site at / and /docs/
-npm run site:build   # assemble static output in site-build/
-npm run site:serve   # serve an existing site-build/ locally
-npm run docs:build   # build only the static docs app
-npm run docs:serve   # preview the existing site-build/ output
+# Not sure how something was decided? Search.
+npx @shahmilsaari/memory-core search "caching strategy"
+
+# See what's saved
+npx @shahmilsaari/memory-core list --type rule
+
+# Export rules for version control and team sharing
+npx @shahmilsaari/memory-core export
 ```
 
+---
+
+## Commands
+
 ### `init` — Set up a project
 
 ```bash
@@ -224,57 +241,45 @@ npx @shahmilsaari/memory-core init
 
 Walks you through:
 - PostgreSQL connection URL — **tested live, retries until connected**
-- Ollama URL — **tested live, retries until reachable** (used for embeddings)
+- Ollama URL — **tested live, retries until reachable**
 - Code-checking provider — **Ollama (local), OpenAI, Anthropic, or MiniMax**
 - Code-checking model — picked from a list, verified before continuing
 - Project name, type, architecture, language
-- Which agents to generate files for — **multi-select, all pre-checked, Space to deselect** — saved to `.memory-core.json`
+- Which agents to generate files for — multi-select, all pre-checked
 - Hook mode — **advisory** (logs violations, never blocks) or **strict** (blocks commits)
-- Whether to enable caveman mode (optional token saver)
-
-Generates config files for every selected AI agent, saves your choices to `.memory-core.json`, enables auto-sync by default, and automatically adds all generated files to `.gitignore` under a `# memory-core generated files` block.
+- Whether to enable caveman mode
 
-At the end, the banner shows live ✓/✗ status for PostgreSQL and Ollama so you know everything is working.
+Generates config files for every selected agent, installs the pre-commit hook, and auto-syncs by default.
 
 ---
 
 ### `sync` — Refresh all agent files
 
-Regenerate every agent file on demand. This still exists even though `remember`, `import`, `edit`, `remove`, `forget`, and `ignore` auto-sync by default after changing memories.
-
 ```bash
 npx @shahmilsaari/memory-core sync
 ```
 
-Multi-selects which agents to sync (pre-checked from your `.memory-core.json` config). Skips files that haven't changed and reports how many were updated vs already up to date:
+Regenerates every agent instruction file from your current rules. Reports updated vs already up to date:
 
 ```
   3 updated, 11 already up to date
 ```
 
-Use `--no-sync` on memory-changing commands when you want to save database changes without regenerating files immediately.
-
-Manage the default:
-
+Turn off auto-sync when you want to batch memory edits, then sync once:
 ```bash
-npx @shahmilsaari/memory-core auto-sync        # show current setting
-npx @shahmilsaari/memory-core auto-sync off    # save only, sync manually later
-npx @shahmilsaari/memory-core auto-sync on     # restore default behavior
+npx @shahmilsaari/memory-core auto-sync off
+npx @shahmilsaari/memory-core auto-sync on
 ```
 
-Auto-sync failures are non-fatal. If regeneration cannot run, memory-core prints the reason and tells you to run `memory-core sync` manually.
-
 ---
 
 ### `remember` — Save a decision
 
-Made a decision your team should never forget? Save it.
-
 ```bash
 npx @shahmilsaari/memory-core remember "Controllers must never call the database directly"
 ```
 
-It will ask you *why* — that reason gets stored alongside the rule and shown to AI agents and developers when a violation is caught.
+It will ask you *why* — the reason gets stored alongside the rule and shown when a violation is caught.
 
 With flags (skip the prompts):
 ```bash
@@ -292,56 +297,28 @@ npx @shahmilsaari/memory-core remember "Use DTOs for all API responses" \
 |---|---|---|
 | `--type` | `decision` `rule` `pattern` `note` | `decision` |
 | `--scope` | `global` `project` | `project` |
-| `--reason` | any text | asked interactively; fallback is stored if blank |
+| `--reason` | any text | asked interactively |
 | `--applies-to` | comma-separated use cases | none |
 | `--avoid-when` | comma-separated exceptions | none |
 | `--example` | comma-separated examples | none |
-| `--source` | source note, ticket, or review | none |
 | `--tags` | comma-separated | none |
 
-Structured context is stored in the database as JSON and rendered into generated agent files as `Why`, `Use when`, `Avoid when`, and `Examples`, which gives AI agents clearer guidance than a flat rule sentence.
-
----
-
-### `search` — Find a rule or decision
-
-```bash
-npx @shahmilsaari/memory-core search "error handling"
-npx @shahmilsaari/memory-core search "auth strategy" --limit 10
-```
-
-Uses AI search — finds related rules even if you don't use the exact words.
-
----
-
-### `seed` — Load predefined rules
-
-281 best-practice rules across all supported architectures, each with a plain-English reason explaining why the rule exists.
-
-```bash
-npx @shahmilsaari/memory-core seed                              # all architectures
-npx @shahmilsaari/memory-core seed --arch clean-architecture   # one only
-npx @shahmilsaari/memory-core seed --force                     # re-seed existing
-```
-
 ---
 
 ### `watch` — Catch violations as you type
 
 ```bash
 npx @shahmilsaari/memory-core watch
+npx @shahmilsaari/memory-core watch --auto-fix   # let AI rewrite violations automatically
+npx @shahmilsaari/memory-core watch --path src/  # watch a specific folder only
+npx @shahmilsaari/memory-core watch --scan-on-start  # scan all tracked files once, then watch
+npx @shahmilsaari/memory-core watch --verbose
+npx @shahmilsaari/memory-core watch --debug
 ```
 
-Runs in the background and checks each file the moment you save it. You see violations immediately — before you even think about committing.
+Runs in the background and checks each file the moment you save it. Violations appear immediately:
 
 ```
-  archmind watch — real-time rule enforcement
-
-  watching: /your/project
-  model:    llama3.2
-  rules:    24
-  ctrl+c to stop
-
   [10:42:11] saved: src/controllers/user.ts
 
   ✗ 1 violation in src/controllers/user.ts
@@ -353,16 +330,23 @@ Runs in the background and checks each file the moment you save it. You see viol
       Fix:    Move to UserService.hashPassword()
 ```
 
-Options:
+With `--auto-fix`, when a violation is detected the AI rewrites the file and saves the fix as a new rule so the same mistake doesn't repeat.
+
+---
+
+### `check` — Manual check
+
 ```bash
-npx @shahmilsaari/memory-core watch --path src/   # watch a specific folder only
-npx @shahmilsaari/memory-core watch --scan-on-start  # snapshot-scan tracked files once, then keep watching
-npx @shahmilsaari/memory-core watch --verbose     # show extra details
-npx @shahmilsaari/memory-core watch --debug       # show prompt, diff, and raw model output
+npx @shahmilsaari/memory-core check --staged              # check staged files (same as hook)
+npx @shahmilsaari/memory-core check --staged --dry-run   # show results without blocking
+npx @shahmilsaari/memory-core check --staged --fast      # deterministic-only, no AI
+npx @shahmilsaari/memory-core check --file src/user.ts   # check a single file
+npx @shahmilsaari/memory-core check --all                 # scan all tracked source files
+npx @shahmilsaari/memory-core check --commit-msg          # check .git/COMMIT_EDITMSG
+npx @shahmilsaari/memory-core check --ci                  # CI mode using memories.json
 ```
 
-Only checks source files — ignores `node_modules`, `dist`, config files, JSON, etc.  
-`--scan-on-start` is useful after a big refactor because it refreshes current live stats automatically before normal save-based watch mode begins.
+`--dry-run` runs the full check pipeline but exits 0, so CI or pre-commit can report violations without blocking. `--fast` skips AI for a low-latency check. `--file` checks a single file retroactively (treats entire file content as the diff).
 
 ---
 
@@ -375,204 +359,141 @@ npx @shahmilsaari/memory-core dashboard --path /absolute/path/to/project
 npx @shahmilsaari/memory-core dashboard --no-watch
 ```
 
-Starts a local Svelte dashboard at `http://localhost:5178` by default. The dashboard includes:
-
-- WebSocket live feed for `watch` events
-- terminal-style violation details with file, line, rule, reason, issue, fix, and code context
-- PostgreSQL connection status, database name, host, and redacted URL
-- code-checking model status, resolved Ollama model, embedding model, and provider
-- architecture-aware rule browser filtered to the project initialized during `init`
-- stats for most violated rules and files
-- live reload for `.env`, `.memory-core.env`, `.memory-core.json`, and `.memory-core-stats.json`
+Starts a local Svelte dashboard at `http://localhost:5178`. What you get:
 
-The WebSocket endpoint is local: `ws://localhost:5178/ws`. Runtime config changes are reloaded and pushed to the browser without restarting the dashboard after the dashboard process is running.
-When `--path` is provided, it must point to the project root (the directory containing `.memory-core.json`).
+- **Live violations feed** — WebSocket push, no polling
+- **Model switcher** — change provider and model from the UI; takes effect immediately
+- **Token usage** — AI call count and tokens used; Ollama shows "LOCAL (FREE)"
+- **Actions panel** — Sync Agents, Check All, Tune Rules without touching the terminal
+- **PostgreSQL health** — connection status, database name, host
+- **Rule browser** — filtered to your project's architecture profile
+- **Stats** — most violated rules and files
 
 ---
 
-### `check` — Manual check (for CI)
-
-```bash
-npx @shahmilsaari/memory-core check --staged              # check staged files
-npx @shahmilsaari/memory-core check --staged --fast       # deterministic-only staged check
-npx @shahmilsaari/memory-core check --staged --verbose    # with extra detail
-npx @shahmilsaari/memory-core check --staged --debug      # show prompt, diff, and raw model output
-npx @shahmilsaari/memory-core check --commit-msg          # check .git/COMMIT_EDITMSG
-npx @shahmilsaari/memory-core check --commit-msg <file>   # check a specific message file
-npx @shahmilsaari/memory-core check --ci                  # CI mode using memories.json
-npx @shahmilsaari/memory-core check --all                 # scan all tracked source files
-npx @shahmilsaari/memory-core check --all --path src/     # scan only tracked files under src/
-```
-
-`--staged` is the same path used by the pre-commit hook. Add `--fast` to skip AI and memory retrieval for a low-latency deterministic check. `--commit-msg` validates a commit message file against `commitRules` — this is called automatically by the `commit-msg` hook. `--ci` reads `memories.json` with no database or Ollama required. `--all` and `--ci` are mutually exclusive.
+### `schema` — TypeScript ↔ Go struct alignment
 
----
-
-### `hook install` — Install hooks
+Catch field drift between TypeScript interfaces and Go structs automatically.
 
 ```bash
-npx @shahmilsaari/memory-core hook install             # advisory mode (default)
-npx @shahmilsaari/memory-core hook install --advisory  # logs violations, never blocks
-npx @shahmilsaari/memory-core hook install --strict    # blocks commits on violations
-npx @shahmilsaari/memory-core hook install --fast      # deterministic-only hook
-```
-
-Installs **two** git hooks:
-- `.git/hooks/pre-commit` — checks staged code against architecture rules.
-- `.git/hooks/commit-msg` — checks commit messages against `commitRules` (see `commit-rules` command).
-
-**Advisory mode (default):** violations are logged but the commit always goes through.
-
-**Strict mode:** violations block the commit. You see exactly what's wrong:
-
-```
-  ✗ 2 rule violations found — commit blocked
-
-  [1] Thin controllers  ×2
-      src/controllers/user.ts:32   Password validation in route handler
-      src/controllers/auth.ts:18   DB query inside controller
+# Define a pair to track
+npx @shahmilsaari/memory-core schema add \
+  --ts src/types/user.ts \
+  --go internal/models/user.go
 
-  [2] src/domain/user.entity.ts:5
-      Rule:   Domain has zero external imports
-      Issue:  Imports 'typeorm' directly
-      Fix:    Define IUserRepository interface in domain/
+# List tracked pairs
+npx @shahmilsaari/memory-core schema list
 
-  To bypass: MEMORY_CORE_SKIP_HOOK=1 git commit
-  Manage rules: memory-core commit-rules --list
+# Check all pairs for field drift
+npx @shahmilsaari/memory-core schema check
 ```
 
-```bash
-npx @shahmilsaari/memory-core hook uninstall   # remove both hooks
-```
+When a field is added to one side but not the other, `schema check` reports it as a violation.
 
 ---
 
-### `list` — List memories from the database
+### `hook install` — Install pre-commit and commit-msg hooks
 
 ```bash
-npx @shahmilsaari/memory-core list
+npx @shahmilsaari/memory-core hook install             # advisory mode (default)
+npx @shahmilsaari/memory-core hook install --strict    # block commits on violations
+npx @shahmilsaari/memory-core hook install --fast      # deterministic-only check
+npx @shahmilsaari/memory-core hook uninstall
 ```
 
-By default, shows memories relevant to the current project context: detected stack, current project name, plus shared/global memories. Use `--all` for the old database-wide view.
+**Advisory mode (default):** violations are logged but the commit always goes through.
 
+**Strict mode:** violations block the commit. You see exactly what's wrong and how to fix it.
+
+To bypass strict mode in an emergency:
 ```bash
-npx @shahmilsaari/memory-core list --all
-npx @shahmilsaari/memory-core list --type rule
-npx @shahmilsaari/memory-core list --scope global
-npx @shahmilsaari/memory-core list --arch clean-architecture
-npx @shahmilsaari/memory-core list --project my-api
-npx @shahmilsaari/memory-core list --limit 50
+MEMORY_CORE_SKIP_HOOK=1 git commit -m "..."
 ```
 
-| Flag | What it does |
-|---|---|
-| `--type <type>` | Filter by type: `decision` `rule` `pattern` `note` |
-| `--scope <scope>` | Filter by scope: `global` `project` |
-| `--arch <architecture>` | Filter by architecture profile |
-| `--project <name>` | Filter by project name |
-| `--all` | Show the full shared database |
-| `--current` | Explicitly use the current project context |
-| `--limit <n>` | Max results (default 200) |
+Every bypass is tracked. If you don't provide a reason, memory-core will ask you on the next commit.
 
 ---
 
-### `remove` — Delete a memory
+### `search` — Find a rule
 
 ```bash
-npx @shahmilsaari/memory-core remove <id>
-npx @shahmilsaari/memory-core remove <id> --no-sync
+npx @shahmilsaari/memory-core search "error handling"
+npx @shahmilsaari/memory-core search "auth strategy" --limit 10
 ```
 
-Deletes a memory by its ID. Get the ID from `list` or `search`.
+Uses AI search — finds related rules even if you don't use the exact words.
 
 ---
 
-### `forget` — Bulk-delete memories
+### `seed` — Load predefined rules
+
+281 best-practice rules across all supported architectures, each with a plain-English reason.
 
 ```bash
-npx @shahmilsaari/memory-core forget --tag nextjs --scope global
-npx @shahmilsaari/memory-core forget --type ignore
-npx @shahmilsaari/memory-core forget --arch nuxt
+npx @shahmilsaari/memory-core seed                              # all architectures
+npx @shahmilsaari/memory-core seed --arch clean-architecture   # one only
+npx @shahmilsaari/memory-core seed --force                     # re-seed existing
 ```
 
-Deletes memories by filter. At least one filter is required, so an empty `forget` command cannot wipe the database by accident.
-
-| Flag | What it does |
-|---|---|
-| `--tag <tag>` | Delete memories with a tag |
-| `--scope <scope>` | Filter by scope: `global` `project` |
-| `--type <type>` | Filter by type |
-| `--arch <architecture>` | Filter by architecture profile |
-| `--no-sync` | Skip automatic agent file regeneration |
-
 ---
 
-### `edit` — Edit a memory
+### `list`, `remove`, `edit` — Manage your rules
 
 ```bash
+npx @shahmilsaari/memory-core list
+npx @shahmilsaari/memory-core list --type rule
+npx @shahmilsaari/memory-core list --scope global
+npx @shahmilsaari/memory-core list --arch clean-architecture
+
+npx @shahmilsaari/memory-core remove <id>
 npx @shahmilsaari/memory-core edit <id>
-npx @shahmilsaari/memory-core edit <id> --no-sync
 ```
 
-Opens the memory interactively so you can update its content, reason, structured context, tags, type, or scope.
-
 ---
 
-### `export` — Export memories to a file
+### `export` / `import` — Share rules with your team
 
 ```bash
+# Export your rules to a file (commit this alongside your code)
 npx @shahmilsaari/memory-core export
-npx @shahmilsaari/memory-core export --output path/to/my-rules.json
-```
-
-Exports all memories from the database to `memories.json` in the project root (or the path you specify). Makes your rules portable and version-controllable — commit the file alongside your code.
 
----
-
-### `import` — Import memories from a file
-
-```bash
+# Import from a file or URL
 npx @shahmilsaari/memory-core import
-npx @shahmilsaari/memory-core import --file path/to/my-rules.json
+npx @shahmilsaari/memory-core import --file path/to/rules.json
 npx @shahmilsaari/memory-core import --url https://example.com/team-rules.json
-npx @shahmilsaari/memory-core import --no-sync
 ```
 
-Imports memories into the local database. Skips duplicates by content hash — safe to run more than once.
-
-| Flag | What it does |
-|---|---|
-| `--file <path>` | Import from a custom local file path |
-| `--url <url>` | Import from a remote URL |
-| `--no-sync` | Skip automatic agent file regeneration |
+Skips duplicates — safe to run multiple times.
 
 ---
 
-### `ignore` — Mark false positives
+### `ignore` / `allow` — Handle exceptions
 
 ```bash
-npx @shahmilsaari/memory-core ignore "controllers may import prisma directly in migration scripts"
-```
-
-Saves a pattern so the hook and watcher never flag it again. Useful for intentional exceptions to a rule.
+# Save a false-positive pattern — never flagged again
+npx @shahmilsaari/memory-core ignore "controllers may import prisma in migration scripts"
+npx @shahmilsaari/memory-core ignore --list
+npx @shahmilsaari/memory-core ignore --remove <id>
 
-```bash
-npx @shahmilsaari/memory-core ignore --list          # show all saved ignore patterns
-npx @shahmilsaari/memory-core ignore --remove <id>   # delete an ignore pattern
-npx @shahmilsaari/memory-core ignore "..." --no-sync # save without regenerating agent files
+# Allow an intentional project pattern
+npx @shahmilsaari/memory-core allow "generated by sqlc"
+npx @shahmilsaari/memory-core allow --list
 ```
 
 ---
 
-### `allow` — Allow intentional project patterns
+### `stats` / `tune` — Manage noisy rules
 
 ```bash
-npx @shahmilsaari/memory-core allow "generated by sqlc"
-npx @shahmilsaari/memory-core allow --list
-npx @shahmilsaari/memory-core allow --remove "generated by sqlc"
+npx @shahmilsaari/memory-core stats           # show violation counts and false-positive rates
+npx @shahmilsaari/memory-core stats --tune    # show only noisy rules with their disable commands
+npx @shahmilsaari/memory-core stats --reset   # clear all counters
+
+npx @shahmilsaari/memory-core tune            # interactively silence noisy rules
+npx @shahmilsaari/memory-core tune --yes      # silence all qualifying rules automatically
 ```
 
-Stores lightweight per-project allowlist strings in `.memory-core.json`. Hook and watch checks treat these patterns as intentional before surfacing violations.
+A rule with a >40% false-positive rate shows up in `--tune`. The `tune` command lets you silence it interactively.
 
 ---
 
@@ -581,20 +502,11 @@ Stores lightweight per-project allowlist strings in `.memory-core.json`. Hook an
 ```bash
 npx @shahmilsaari/memory-core commit-rules "^(feat|fix|chore)" --message "Use conventional commits"
 npx @shahmilsaari/memory-core commit-rules "^WIP" --message "Don't commit WIP" --negate
-npx @shahmilsaari/memory-core commit-rules "PROJ-\d+" --message "Reference a JIRA ticket" --advisory
 npx @shahmilsaari/memory-core commit-rules --list
 npx @shahmilsaari/memory-core commit-rules --remove "^WIP"
 ```
 
-Stores regex-based rules in `.memory-core.json` under `commitRules`. The `commit-msg` git hook (installed by `hook install`) validates every commit message against these rules before the commit is accepted.
-
-| Flag | What it does |
-|---|---|
-| `--message <msg>` | Required. Error message shown on violation. |
-| `--negate` | Pattern must NOT match (default: must match) |
-| `--advisory` | Warn only — do not block the commit |
-| `--list` | Show all saved commit rules |
-| `--remove <pattern>` | Remove a rule by pattern |
+The `commit-msg` git hook validates every commit message against these rules.
 
 ---
 
@@ -604,101 +516,43 @@ Stores regex-based rules in `.memory-core.json` under `commitRules`. The `commit
 npx @shahmilsaari/memory-core ci-setup
 ```
 
-Generates `.github/workflows/memory-core.yml`. Adds a PR check that runs `npx @shahmilsaari/memory-core check --ci`, using `memories.json` so CI can enforce architecture rules without a project-local database.
-
----
-
-### `stats` — Violation counters
-
-```bash
-npx @shahmilsaari/memory-core stats
-npx @shahmilsaari/memory-core stats --tune
-npx @shahmilsaari/memory-core stats --reset
-```
-
-Shows which rules fire most often and which files have the most violations. Each rule shows hit count and false-positive rate where available.
-
-- `--tune` shows only noisy rules (>40% false-positive rate) with their exact disable commands.
-- `--reset` clears all counters and recent violation history.
-- Live watch-state counters are shown when available.
+Generates `.github/workflows/memory-core.yml`. Adds a PR check using `memories.json` — no project database needed in CI.
 
 ---
 
-### `tune` — Silence noisy rules
+### `status` — See your current setup
 
 ```bash
-npx @shahmilsaari/memory-core tune
-npx @shahmilsaari/memory-core tune --threshold 30
-npx @shahmilsaari/memory-core tune --yes
+npx @shahmilsaari/memory-core status
 ```
 
-Interactively reviews rules with a high false-positive rate and adds them to `allowPatterns` in `.memory-core.json`.
-
-| Flag | What it does |
-|---|---|
-| `--threshold <n>` | False-positive % cutoff (default `40`) |
-| `--min-count <n>` | Minimum hits required (default `5`) |
-| `--yes` | Silence all qualifying rules without prompting |
+Shows project name, provider/model, agents, hook state, generated files, and health checks for PostgreSQL and Ollama.
 
 ---
 
-### `reset` vs `uninstall` — Cleanup commands
-
-Use `reset` when you want to keep using memory-core but need to regenerate or reinitialize project files. Use `uninstall` when you want memory-core removed from the current project.
-
-| Command | User intent | What it removes | Database |
-|---|---|---|---|
-| `reset --soft` | Regenerate agent files from a clean slate | Generated agent files only | Kept |
-| `reset` | Reinitialize memory-core in this project | Generated agent files, `.memory-core.json`, hook | Kept |
-| `reset --db` | Reinitialize and clear stored memories | Same as `reset` | Drops `memories` after confirmation |
-| `uninstall` | Remove memory-core from this project | Generated files, config/env/state, CI workflow, hook, `.gitignore` block | Kept |
-| `uninstall --db` | Remove project footprint and stored memory table | Same as `uninstall` | Drops `memories` after confirmation |
-
-### `reset` — Reinitialize generated files
-
-```bash
-npx @shahmilsaari/memory-core reset              # remove generated files + .memory-core.json + hook
-npx @shahmilsaari/memory-core reset --soft       # keep config and DB, remove only generated files
-npx @shahmilsaari/memory-core reset --db         # also drop the memories table from the database
-```
-
-Use this when memory-core should stay part of the project, but generated files need to be rebuilt or the project config should be recreated. Use `--soft` for the safest regeneration path.
+### `reset` vs `uninstall` — Cleanup
 
-### `uninstall` — Remove memory-core from a project
+| Command | What it does | Database |
+|---|---|---|
+| `reset --soft` | Remove generated agent files only | Kept |
+| `reset` | Remove generated files + config + hook | Kept |
+| `reset --db` | Same as reset + drop memories table | Dropped (with confirmation) |
+| `uninstall` | Remove everything: files, config, hook, gitignore block | Kept |
+| `uninstall --db` | Same as uninstall + drop memories table | Dropped (with confirmation) |
 
 ```bash
-npx @shahmilsaari/memory-core uninstall          # remove generated files, config, env, hook, stats, and gitignore block
-npx @shahmilsaari/memory-core uninstall --db     # also drop the memories table after confirmation
+npx @shahmilsaari/memory-core reset
+npx @shahmilsaari/memory-core reset --soft
+npx @shahmilsaari/memory-core uninstall
 ```
 
-Use this when you want the project back to a pre-memory-core state. Database deletion is opt-in and only happens with `--db`.
-
 ---
 
-### `global` — Apply rules to every project
-
-```bash
-npx @shahmilsaari/memory-core global
-```
+## Supported AI agents
 
-Writes your rules to the global config of each AI agent — so they follow your rules in every project on your machine, not just the current one.
+memory-core generates instruction files for:
 
-| Agent | Where it writes |
-|---|---|
-| Claude Code | `~/.claude/CLAUDE.md` |
-| GitHub Copilot | VS Code `settings.json` |
-| Cursor | `~/.cursor/rules/memory-core.mdc` |
-| Cline | VS Code `settings.json` |
-| Continue.dev | `~/.continue/config.json` |
-| Aider | `~/.aider.conf.yml` |
-| Zed AI | `~/.config/zed/settings.json` |
-| Windsurf | `~/.windsurf/rules/memory-core.md` |
-
----
-
-## Supported agents
-
-| Agent | File generated |
+| Agent | File |
 |---|---|
 | Claude Code | `CLAUDE.md` |
 | GitHub Copilot | `.github/copilot-instructions.md` |
@@ -721,16 +575,16 @@ Plus shared files: `AI_RULES.md`, `ARCHITECTURE.md`, `PROJECT_MEMORY.md`
 
 ## Architecture profiles
 
-Pick the one that matches how your project is structured.
+Pick the one that matches your project structure:
 
 **Backend**
 | Profile | Use when… |
 |---|---|
-| Clean Architecture | You want strict separation between domain, application, and infrastructure |
-| Modular Monolith | You're building feature modules that might become microservices later |
-| MVC | Standard web app with controllers and services |
-| Hexagonal | You want ports and adapters for maximum testability |
-| Go REST API | Go backend API with idiomatic error handling and clean package structure |
+| Clean Architecture | Strict separation between domain, application, and infrastructure |
+| Modular Monolith | Feature modules that might become microservices later |
+| MVC | Standard controllers + services |
+| Hexagonal | Ports and adapters for maximum testability |
+| Go REST API | Go backend with idiomatic error handling |
 | Laravel | Laravel with service-repository pattern |
 | NestJS | Modules, guards, pipes, DTOs, repository pattern |
 
@@ -740,144 +594,85 @@ Pick the one that matches how your project is structured.
 | React | Functional components, hooks, React Query, Zustand |
 | Vue 3 | Composition API, Pinia, composables |
 | Angular | Standalone components, signals, OnPush strategy |
-| Svelte | Svelte 5 runes, SvelteKit load functions, snippets |
+| Svelte | Svelte 5 runes, SvelteKit load functions |
 | Nuxt 3 | Fullstack Vue with SSR |
 | React Native | Mobile apps |
 
-Fullstack projects get both sections in every generated file.
-
 ---
 
-## Caveman mode (optional)
-
-Cuts AI response length by 65–75% by removing filler words. Opt in during `init`.
+## AI providers
 
-| Level | What it does |
-|---|---|
-| `lite` | Professional and concise |
-| `full` | Caveman-style short answers |
-| `ultra` | Absolute minimum words |
-
----
-
-## Day-to-day workflow
+| Provider | Setup | Use when |
+|---|---|---|
+| Ollama (default) | Local, no API key | You want free, private, offline AI |
+| OpenAI | `CHAT_API_KEY=sk-...` | You want GPT-4o / GPT-4o-mini quality |
+| Anthropic | `CHAT_API_KEY=sk-ant-...` | You want Claude quality |
+| MiniMax | `CHAT_API_KEY=...` | Cost-effective cloud option |
 
+Switch without rerunning init:
 ```bash
-# Starting a new project
-cd my-api
-npx @shahmilsaari/memory-core init   # verifies connections, picks model, selects agents, installs hook
-npx @shahmilsaari/memory-core seed   # load 281 best-practice rules
-
-# Made an architectural decision? Save it.
-npx @shahmilsaari/memory-core remember "All auth goes through middleware, never in controllers" \
-  --type decision --scope global
-
-# Optional: refresh agent files manually anytime
-npx @shahmilsaari/memory-core sync
-
-# Not sure how something was decided? Search.
-npx @shahmilsaari/memory-core search "caching strategy"
-
-# Inspect current setup, provider, model, and health checks
-npx @shahmilsaari/memory-core status
-
-# Open the local command center with live watch/config updates
-npx @shahmilsaari/memory-core dashboard
-
-# Switch code-checking provider or model without rerunning init
-npx @shahmilsaari/memory-core provider set openai --model gpt-4o-mini --api-key $OPENAI_API_KEY
+npx @shahmilsaari/memory-core provider set openai --model gpt-4o --api-key sk-...
 npx @shahmilsaari/memory-core model set qwen2.5-coder --provider ollama
-
-# See what rules are saved
-npx @shahmilsaari/memory-core list --type rule
-
-# Export rules to version control
-npx @shahmilsaari/memory-core export
-
-# Commit code → hook checks it automatically before committing
-git commit -m "add user endpoint"
 ```
 
+Or switch from the dashboard UI — takes effect immediately, no restart needed.
+
 ---
 
 ## Environment variables
 
-memory-core creates `.memory-core.env` automatically during `init`. You can also set these manually:
+memory-core creates `.memory-core.env` automatically during `init`.
 
-| Variable | Required | Default | What it does |
-|---|---|---|---|
-| `DATABASE_URL` | Yes | — | PostgreSQL connection string |
-| `OLLAMA_URL` | No | `http://localhost:11434` | Where Ollama is running (used for embeddings) |
-| `OLLAMA_MODEL` | No | `nomic-embed-text` | Model used for search (embeddings) — always Ollama |
-| `CHAT_PROVIDER` | No | `ollama` | Provider for code checking: `ollama`, `openai`, `anthropic`, `minimax` |
-| `CHAT_MODEL` | No | `llama3.2` | Model used for code checking — chosen during `init` |
-| `CHAT_API_KEY` | No | — | API key for OpenAI / Anthropic / MiniMax (not needed for Ollama) |
-| `OLLAMA_CHAT_MODEL` | No | `llama3.2` | Legacy alias for `CHAT_MODEL` when provider is `ollama` |
+| Variable | Default | What it does |
+|---|---|---|
+| `DATABASE_URL` | — | PostgreSQL connection string (required) |
+| `OLLAMA_URL` | `http://localhost:11434` | Ollama server URL (used for embeddings) |
+| `OLLAMA_MODEL` | `nomic-embed-text` | Embedding model (always Ollama) |
+| `CHAT_PROVIDER` | `ollama` | Code-checking provider: `ollama`, `openai`, `anthropic`, `minimax` |
+| `CHAT_MODEL` | `llama3.2` | Code-checking model |
+| `CHAT_API_KEY` | — | API key for cloud providers |
 
 ---
 
 ## Troubleshooting
 
 **`extension "vector" is not available`**
-pgvector isn't installed for your PostgreSQL version. Follow the [pgvector install steps](#pgvector) above.
+pgvector isn't installed for your PostgreSQL version. Follow the [pgvector steps](#pgvector) above.
 
 **`Ollama not running — skipping rule check`**
 Start Ollama: `brew services start ollama` (macOS) or `ollama serve` (Linux).
 
 **`Chat model "llama3.2" not found`**
-Run `ollama pull llama3.2`. Or switch provider/model with `npx @shahmilsaari/memory-core provider set ...` or `npx @shahmilsaari/memory-core model set ...`.
-
-**Using an API key instead of Ollama for code checking**
-During `init` choose OpenAI, Anthropic, or MiniMax when prompted for the check provider. Or switch later:
-```bash
-npx @shahmilsaari/memory-core provider set openai --model gpt-4o --api-key sk-...
-```
-
-Equivalent manual `.memory-core.env` settings:
-```
-CHAT_PROVIDER=openai
-CHAT_MODEL=gpt-4o
-CHAT_API_KEY=sk-...
-```
-Embeddings always use Ollama (`nomic-embed-text`) regardless of provider.
+Run `ollama pull llama3.2`, or switch provider: `npx @shahmilsaari/memory-core provider set openai --model gpt-4o-mini --api-key sk-...`
 
 **`DATABASE_URL is not set`**
-Run `npx @shahmilsaari/memory-core init` — it will create the `.memory-core.env` file for you.
+Run `npx @shahmilsaari/memory-core init` — it creates `.memory-core.env` for you.
 
-**Not sure what memory-core is configured to use**
-Run `npx @shahmilsaari/memory-core status`.
-
-**Need to verify the model/database setup**
-Run `npx @shahmilsaari/memory-core model doctor`.
+**Not sure what memory-core is using**
+Run `npx @shahmilsaari/memory-core status` or `npx @shahmilsaari/memory-core model doctor`.
 
 **`createdb: role does not exist`**
 ```bash
 createuser -s $(whoami)
 ```
 
-**Hook is flagging JSON or config files**
-It won't — the hook only checks source code files: `.ts .tsx .js .jsx .py .php .rb .go .java .cs .swift .kt .rs .vue .svelte`. Everything else is skipped automatically.
+**Hook is flagging something intentional**
+Save an ignore pattern: `npx @shahmilsaari/memory-core ignore "your exception here"`
 
-**Hook is flagging something that's intentional**
-Save an ignore pattern: `npx @shahmilsaari/memory-core ignore "your exception here"`. The hook and watcher will never flag it again.
+**I bypassed the hook by accident and now it keeps asking**
+That's bypass tracking. Run `MEMORY_CORE_SKIP_HOOK=1 git commit` with a reason the next time, or run `npx @shahmilsaari/memory-core stats` to see your bypass history.
 
 ---
 
-## Release checks
-
-Before publishing, run the same checks as CI:
+## Caveman mode (optional)
 
-```bash
-npm run lint
-npm run typecheck
-npm test
-npm run build
-npm run smoke:pack
-npm run smoke:npx
-```
+Cuts AI response length by 65–75% by removing filler words. Opt in during `init`.
 
-`smoke:pack` verifies the npm tarball includes the built CLI plus templates/profiles.
-`smoke:npx` installs that tarball into a fresh temporary project and runs `npx --no-install memory-core init --quick`.
+| Level | What it does |
+|---|---|
+| `lite` | Professional and concise |
+| `full` | Caveman-style short answers |
+| `ultra` | Absolute minimum words |
 
 ---
 
@@ -886,33 +681,29 @@ npm run smoke:npx
 | | Feature |
 |---|---|
 | ✓ | Watch mode — real-time violation alerts on save |
-| ✓ | Model picker — choose your Ollama model during init |
-| ✓ | Connection validation — PostgreSQL and Ollama verified during setup |
-| ✓ | Svelte 5 / SvelteKit profile and 37 rules |
-| ✓ | NestJS profile and 39 rules |
-| ✓ | Hook auto-prompt — hook mode offered during init, no separate step needed |
-| ✓ | CI/CD — `ci-setup` generates GitHub Actions workflow for PR enforcement |
-| ✓ | Agent selection — choose which agents to generate files for during init |
-| ✓ | Auto-sync — memory-changing commands refresh selected agent files by default |
-| ✓ | Export / import — portable memories.json for version control and team sharing |
-| ✓ | List / remove / edit — full CRUD for stored memories |
-| ✓ | False positive tagging — `ignore` and `allow` save exceptions for hook and watcher |
-| ✓ | Cleanup commands — `reset` regenerates/reinitializes files; `uninstall` removes memory-core |
-| ✓ | Test suite — 94 tests using Node.js built-in `node:test` |
+| ✓ | AI auto-fix — violations detected → AI rewrites the file |
+| ✓ | Dry-run mode — full check pipeline, exits 0 |
+| ✓ | Schema alignment rules — TypeScript↔Go struct field drift detection |
+| ✓ | Bypass tracking — every hook bypass is counted and visible |
+| ✓ | Token usage tracking — AI call counts across all providers |
+| ✓ | Dashboard model switcher — change provider/model from the UI |
+| ✓ | Dashboard actions panel — Sync, Check All, Tune from UI |
+| ✓ | WebSocket-only stats — live push, no polling |
 | ✓ | Multi-provider code checking — Ollama, OpenAI, Anthropic, MiniMax |
-| ✓ | Context-aware retrieval — surface the most relevant rules for the file being edited |
-| ✓ | Setup management — `status`, `provider set`, `model set`, `model doctor` |
-| ✓ | `--debug` flag — verbose output for diagnosing hook and watcher issues |
-| ✓ | Local Svelte dashboard — WebSocket live feed, runtime status, stats, and rules browser |
-| ✓ | Rule cache — 5-min TTL cache, invalidated by config or DB version change |
-| ✓ | Batch suppression — same rule ≥3× on same file auto-suppressed with a notice |
-| ✓ | False-positive tracking — `{ count, falsePositives }` stored per rule in stats |
-| ✓ | Violation clustering — violations grouped by rule, compact multi-location display |
-| ✓ | Auto-tuning — `memory-core tune` silences noisy rules interactively |
-| ✓ | Commit message linting — `commit-rules` + `commit-msg` git hook |
-| | Model guidance during init — recommend a model based on machine specs |
-| | Violation → rule pipeline — auto-suggest a new rule when the same violation repeats |
-| | Team sync — shared database so the whole team works from the same rule set |
+| ✓ | Pre-commit hook (advisory + strict modes) |
+| ✓ | Commit message linting — `commit-rules` + `commit-msg` hook |
+| ✓ | CI/CD — GitHub Actions workflow generation |
+| ✓ | 14 agent file generators + 3 shared files |
+| ✓ | 281 seeded best-practice rules across 13 architecture profiles |
+| ✓ | AI-powered rule search |
+| ✓ | Export / import — portable `memories.json` |
+| ✓ | Auto-tuning — silence noisy rules interactively |
+| ✓ | False-positive tracking per rule |
+| ✓ | Import graph analysis — structural boundary checking |
+| ✓ | Local Svelte dashboard with WebSocket live feed |
+| | Model guidance during init — recommend model based on machine specs |
+| | Team sync — shared database for the whole team |
+| | Violation → rule pipeline — auto-suggest rules when violations repeat |
 
 ---