@tpsdev-ai/flair 0.26.0 → 0.27.0

package/docs/integrations.md

@@ -0,0 +1,197 @@
+# Flair integrations
+
+Where Flair already runs. Each integration shown here is a working surface — the same memory, federated across all of them, scoped per-agent by Ed25519 keys.
+
+> **The point.** Memory should follow the agent across orchestrators. Every entry below pulls from the same Flair instance, sees the same `agentId` namespace, respects the same isolation. Pick whichever harness you're shipping in; the memory layer doesn't care.
+
+---
+
+## Quick install matrix
+
+| Surface | Install path | Auth | Notes |
+|---------|--------------|------|-------|
+| **Claude Code** | [`flair-mcp`](#claude-code-cursor-codex-gemini-cli-continuedev-via-flair-mcp) | MCP config | Standard MCP server |
+| **Cursor** | [`flair-mcp`](#claude-code-cursor-codex-gemini-cli-continuedev-via-flair-mcp) | MCP config | Standard MCP server |
+| **Continue.dev** | [`flair-mcp`](#claude-code-cursor-codex-gemini-cli-continuedev-via-flair-mcp) | MCP config | Standard MCP server |
+| **OpenAI Codex CLI** | [`flair-mcp`](#claude-code-cursor-codex-gemini-cli-continuedev-via-flair-mcp) | MCP config | Standard MCP server |
+| **Gemini CLI** | [`flair-mcp`](#claude-code-cursor-codex-gemini-cli-continuedev-via-flair-mcp) | MCP config | Standard MCP server |
+| **Goose** (block/goose) | [`flair-mcp`](#claude-code-cursor-codex-gemini-cli-continuedev-via-flair-mcp) | MCP config | Goose ships native MCP support |
+| **LangGraph (TS)** | [`langgraph-flair`](#langgraph-typescript) | FlairClient | Drop-in `BaseStore` |
+| **OpenClaw** | [`openclaw-flair`](#openclaw) | Ed25519 | Native plugin + context engine |
+| **n8n** | [`n8n-nodes-flair`](#n8n) | FlairApi credential | Three nodes (chat memory, search, store) |
+| **Hermes Agent** | [`hermes-flair`](#hermes-agent) | Ed25519 | Python `MemoryProvider` |
+| **Pi agent** | [`pi-flair`](#pi-agent) | Ed25519 | TS plugin |
+
+Don't see your harness? If it speaks **MCP** — Flair already works with `flair-mcp`. If it has a **custom memory protocol** like LangGraph's `BaseStore` or CrewAI's `RAGStorage`, an adapter is a ~200-line package; [open an issue](https://github.com/tpsdev-ai/flair/issues) or [send a PR](https://github.com/tpsdev-ai/flair).
+
+**Adjacent: memory bridges** — for moving memories between Flair and another memory product. Five bridges ship today (Mem0, ChatGPT exports, claude-project files, agentic-stack, markdown); see [bridges.md](bridges.md). Bridges are import/export plumbing, not live orchestrator integrations.
+
+---
+
+## Claude Code, Cursor, Codex, Gemini CLI, Continue.dev, Goose — via `flair-mcp`
+
+[`@tpsdev-ai/flair-mcp`](https://www.npmjs.com/package/@tpsdev-ai/flair-mcp) is a [Model Context Protocol](https://modelcontextprotocol.io/) server that exposes Flair as a memory tool to any MCP-speaking client. One server, every MCP client.
+
+No install step needed — every snippet below uses `npx -y @tpsdev-ai/flair-mcp`, which fetches and runs the server on demand (zero-install). The fastest path is `flair init`, which detects and wires these clients for you. To wire by hand, drop the relevant snippet into each tool's MCP config:
+
+**Claude Code** (`~/.config/claude-code/config.toml` or per-project `.claude/config.toml`):
+```toml
+[mcp.servers.flair]
+command = "npx"
+args = ["-y", "@tpsdev-ai/flair-mcp"]
+env = { FLAIR_AGENT_ID = "claude-code" }
+```
+
+**Cursor** (`~/.cursor/mcp.json`):
+```json
+{
+  "mcpServers": {
+    "flair": {
+      "command": "npx",
+      "args": ["-y", "@tpsdev-ai/flair-mcp"],
+      "env": { "FLAIR_AGENT_ID": "cursor" }
+    }
+  }
+}
+```
+
+**Codex CLI** (`~/.codex/config.toml`):
+```toml
+[mcp_servers.flair]
+command = "npx"
+args = ["-y", "@tpsdev-ai/flair-mcp"]
+
+[mcp_servers.flair.env]
+FLAIR_AGENT_ID = "codex"
+```
+
+**Gemini CLI** (`~/.gemini/settings.json`): same shape as Cursor.
+
+**Continue.dev** (`~/.continue/config.json`):
+```json
+{
+  "experimental": {
+    "modelContextProtocolServer": {
+      "command": "npx",
+      "args": ["-y", "@tpsdev-ai/flair-mcp"],
+      "env": { "FLAIR_AGENT_ID": "continue" }
+    }
+  }
+}
+```
+
+**Goose** (`~/.config/goose/profiles.yaml`):
+```yaml
+default:
+  extensions:
+    flair:
+      cmd: npx
+      args: ["-y", "@tpsdev-ai/flair-mcp"]
+      envs: { FLAIR_AGENT_ID: goose }
+```
+
+**Auth.** Set `FLAIR_AGENT_ID` to whatever identifier you want this client to claim. The MCP server will prompt you to register that agent on first call (`flair agent add <id>` writes the Ed25519 keypair). Subsequent calls auto-load the key.
+
+Full per-tool walkthrough including troubleshooting: [`docs/mcp-clients.md`](mcp-clients.md).
+
+---
+
+## LangGraph (TypeScript)
+
+[`@tpsdev-ai/langgraph-flair`](https://www.npmjs.com/package/@tpsdev-ai/langgraph-flair) implements LangGraph's `BaseStore`. Drop-in for `InMemoryStore`.
+
+```bash
+npm install @tpsdev-ai/langgraph-flair
+```
+
+```typescript
+import { FlairStore } from "@tpsdev-ai/langgraph-flair";
+import { createReactAgent } from "@langchain/langgraph/prebuilt";
+
+const store = new FlairStore({ agentId: "my-langgraph-agent" });
+const agent = createReactAgent({ llm, tools, store });
+```
+
+Maps LangGraph namespaces to Flair tags, keys to ids, values to JSON content. Search delegates to Flair's HNSW. Filter operators applied client-side. Full mapping table: [`packages/langgraph-flair/README.md`](../packages/langgraph-flair/README.md).
+
+LangGraph **Python** support is on the roadmap (same `BaseStore` shape, Python adapter).
+
+---
+
+## OpenClaw
+
+[`@tpsdev-ai/openclaw-flair`](https://www.npmjs.com/package/@tpsdev-ai/openclaw-flair) is the native OpenClaw plugin. Adds Flair as a memory provider AND registers the `flair` context engine that re-injects PERMANENT-tier rules (SOUL.md, IDENTITY.md, AGENTS.md) every turn.
+
+```bash
+openclaw plugins install @tpsdev-ai/openclaw-flair
+```
+
+Configuration via OpenClaw's standard plugin surface. See [`docs/openclaw.md`](openclaw.md) for the per-agent install pattern, including how to wire SOUL.md so behavioral anchors persist across long sessions without drift.
+
+---
+
+## n8n
+
+[`@tpsdev-ai/n8n-nodes-flair`](https://www.npmjs.com/package/@tpsdev-ai/n8n-nodes-flair) ships three nodes:
+
+- **FlairChatMemory** — drop-in chat-memory for n8n's AI Agent / LangChain workflow nodes. Same role as Postgres / Redis chat memory but with cross-orchestrator portability.
+- **FlairSearch** — semantic search over your Flair memories from any workflow.
+- **FlairApi** credential — Ed25519 keypair entry point for the agentId.
+
+Install via the standard n8n community-node UI (Settings → Community nodes → `@tpsdev-ai/n8n-nodes-flair`) or:
+
+```bash
+cd ~/.n8n && npm install @tpsdev-ai/n8n-nodes-flair
+```
+
+Walkthrough including a worked example flow: [`docs/n8n.md`](n8n.md).
+
+---
+
+## Hermes Agent
+
+[`hermes-flair`](https://github.com/tpsdev-ai/flair/tree/main/packages/hermes-flair) implements Nous Research [Hermes](https://github.com/NousResearch/hermes-agent)'s `MemoryProvider` plugin contract in Python. Bootstrap injection at session start, background prefetch between turns, two tools (`flair_search`, `flair_store`), built-in MEMORY.md mirroring, circuit breaker.
+
+```bash
+hermes plugins install path:/path/to/flair/packages/hermes-flair
+```
+
+Auth: TPS-Ed25519 (the same model the rest of Flair uses) — writes are isolated per agent identity server-side; reads are open within the org for non-private memories, with `visibility: private` staying owner-only. See [SECURITY.md](../SECURITY.md).
+
+---
+
+## Pi agent
+
+[`@tpsdev-ai/pi-flair`](https://www.npmjs.com/package/@tpsdev-ai/pi-flair) is the TS plugin for the [Pi coding agent](https://github.com/mariozechner/pi-coding-agent). Memory + identity for the Pi runtime.
+
+```bash
+npm install @tpsdev-ai/pi-flair
+```
+
+Pi resolves the plugin via its standard plugin config; pin `agentId` per host.
+
+---
+
+## Don't see your harness?
+
+If it speaks MCP, you're already covered — every MCP client works through `flair-mcp` (the section above lists 6 we've explicitly tested).
+
+If it has a custom memory protocol, the adapter pattern is small (~200 lines). LangGraph and Hermes are the reference implementations. **Adapters we'd love to see:**
+
+- LangGraph Python (mirror of our TS adapter)
+- CrewAI (Python `BaseRAGStorage` protocol)
+- AG2 / AutoGen (Python)
+- Mastra (TS, denser thread model)
+- ADK (Google, Python + TS)
+
+[Open an issue](https://github.com/tpsdev-ai/flair/issues) describing the harness and we'll triage. PRs welcome — see [`packages/langgraph-flair`](../packages/langgraph-flair) as the smallest-shape reference.
+
+---
+
+## See also
+
+- [Quickstart](quickstart.md) — `flair init` to working memory in 30 seconds
+- [Memory bridges](bridges.md) — import/export Flair ↔ Mem0, ChatGPT, claude-project, markdown, agentic-stack (five bridges shipped)
+- [Federation](federation.md) — pair instances peer-to-peer for cross-machine sync
+- [Supply-chain policy](supply-chain-policy.md) — what we do to keep this list of integrations safe
+- [The team](the-team.md) — the multi-agent rig that builds Flair, dogfooded on every harness above

package/docs/mcp-clients.md

@@ -0,0 +1,240 @@
+# Flair via MCP — Claude Code, Gemini CLI, OpenAI Codex CLI
+
+Flair ships an MCP server (`@tpsdev-ai/flair-mcp`) that any MCP-compatible client can use as its persistent memory + identity layer. One server, three (and counting) integrations. Switch between agent CLIs without losing your agent's memory.
+
+This page is the install + config snippet for each of the three major CLIs. The bootstrap is the same:
+
+1. Install Flair and create an agent identity (one-time, ~2 min).
+2. Add the MCP server to your CLI of choice (1 command or 1 file).
+3. Verify the agent can call `memory_search` / `memory_store`.
+
+If you've never set up Flair before, do step 1 first. If Flair is already running and you have an agent ID, jump to your CLI section.
+
+---
+
+## Step 1 — Install Flair (do once)
+
+```bash
+# Install Flair globally
+npm install -g @tpsdev-ai/flair
+
+# Initialize the local Harper-backed server
+flair init
+
+# Provision an agent identity. Pick a name — typically per-project, per-purpose,
+# or "me" if you want one durable identity across everything.
+flair agent add my-project
+# → writes ~/.flair/keys/my-project.key (Ed25519 PKCS8) and registers the agent
+
+# Sanity check
+flair status
+```
+
+Flair runs as a local server at `http://127.0.0.1:19926` by default. The MCP server connects to it on demand via Ed25519-signed requests; nothing leaves your machine unless you explicitly route to a remote Flair instance.
+
+---
+
+## Step 2 — Wire the MCP server into your CLI
+
+Pick whichever you use. The MCP server is the same package; only the config syntax differs.
+
+### Claude Code
+
+The canonical approach is the `claude mcp add` CLI (writes to `~/.claude/mcp.json`):
+
+```bash
+claude mcp add flair --scope user \
+  -e FLAIR_AGENT_ID=my-project \
+  -- npx -y @tpsdev-ai/flair-mcp
+```
+
+Verify:
+
+```bash
+claude mcp list
+# → flair (stdio, npx -y @tpsdev-ai/flair-mcp)
+```
+
+Or, if you prefer the project-scoped `.mcp.json` checked into your repo:
+
+```json
+{
+  "mcpServers": {
+    "flair": {
+      "command": "npx",
+      "args": ["-y", "@tpsdev-ai/flair-mcp"],
+      "env": {
+        "FLAIR_AGENT_ID": "my-project"
+      }
+    }
+  }
+}
+```
+
+#### Auto-recall on session start (optional hook)
+
+The MCP server gives the agent *pull* access to memory — it calls `bootstrap` /
+`memory_search` when it decides to. If you'd rather have Flair context loaded
+automatically the moment a session opens (no "call the bootstrap tool" nudge),
+register Flair's `SessionStart` hook. It's a separate bin shipped in the same
+package and is entirely optional — it complements the MCP server, it doesn't
+replace it.
+
+The one-command way (recommended — idempotent, `--dry-run`-able, and
+symmetric with `flair hook uninstall`/`flair hook status`):
+
+```bash
+flair hook install               # wires ~/.claude/settings.json for FLAIR_AGENT_ID/FLAIR_URL
+flair hook install --dry-run     # prints the exact JSON delta, writes nothing
+flair hook status                # wired? correct shape? which agent/instance?
+flair hook uninstall             # removes only Flair's hook entry
+```
+
+`--harness claude-code` is the only supported value today (it's also the
+default) — the flag exists so a future harness is an additive registry entry,
+not a breaking change. `flair doctor` already checks for this same hook (see
+below) and recognizes anything `flair hook install` writes.
+
+Or wire it by hand — add a `SessionStart` hook to `~/.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "FLAIR_AGENT_ID=me npx -y @tpsdev-ai/flair-mcp flair-session-start"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Swap `me` for your `FLAIR_AGENT_ID`. The hook reads Claude Code's SessionStart
+payload on stdin, calls Flair's `bootstrap` (soul + relevant memories +
+predicted context, scoped to your project by the session's working directory),
+and emits it as `hookSpecificOutput.additionalContext` — which Claude Code
+injects into the new session's context. The matcher is omitted, so it fires on
+every session start (`startup`, `resume`, `clear`, `compact`); add
+`"matcher": "startup"` to a hook group if you only want it on fresh sessions.
+
+It honors the same env as the MCP server (`FLAIR_AGENT_ID`, `FLAIR_URL`,
+`FLAIR_KEY_PATH`), plus `FLAIR_HOOK_TIMEOUT_MS` (default 8000, clamped
+500–30000) for the bootstrap timeout.
+
+**It degrades to a no-op, always.** No `FLAIR_AGENT_ID`, Flair down, an auth
+error, or a hung daemon (past the timeout) → the hook prints `{}` and exits 0.
+Claude Code treats that as "no context to add" and starts normally. The hook
+can never block or break session startup. The injected context is clamped to
+≤10,000 characters to keep the session-start payload small.
+
+### Gemini CLI
+
+Edit `~/.gemini/settings.json` (create it if absent):
+
+```json
+{
+  "mcpServers": {
+    "flair": {
+      "command": "npx",
+      "args": ["-y", "@tpsdev-ai/flair-mcp"],
+      "env": {
+        "FLAIR_AGENT_ID": "my-project"
+      }
+    }
+  }
+}
+```
+
+Restart your Gemini CLI session for the config to take effect. Then in chat:
+
+```
+> @flair memory_search "what did we decide about auth last week?"
+```
+
+### OpenAI Codex CLI
+
+Edit `~/.codex/config.toml` (create it if absent):
+
+```toml
+[mcp_servers.flair]
+command = "npx"
+args = ["-y", "@tpsdev-ai/flair-mcp"]
+
+[mcp_servers.flair.env]
+FLAIR_AGENT_ID = "my-project"
+```
+
+For project-scoped trust (per Codex's MCP guide), the same block in `.codex/config.toml` at the project root.
+
+Restart your Codex CLI session and the `flair_*` tools become available to the agent.
+
+---
+
+## Step 3 — Verify
+
+In any of the three CLIs, ask the agent to do this:
+
+> Use the bootstrap tool to load my Flair memory context, then store a memory that says "successful first MCP integration test."
+
+If you see (a) the agent calling the `bootstrap` tool returning soul + recent memories, and (b) `memory_store` confirming a write — you're wired up. The memory now persists across CLI sessions AND across CLIs. Switch to a different CLI tomorrow and `memory_search "MCP integration test"` will find it.
+
+---
+
+## What the MCP server exposes
+
+Eleven tools, kept deliberately small:
+
+| Tool | What it does |
+|---|---|
+| `memory_search` | Semantic search across your agent's memories |
+| `memory_store` | Save a memory with type, durability, tags. Auto-dedups near-duplicates |
+| `memory_update` | Update an existing memory by ID — overwrite in place, or version it with `preserveHistory` |
+| `memory_get` | Fetch a specific memory by ID |
+| `memory_delete` | Remove a memory |
+| `relationship_store` | Record a subject-predicate-object relationship triple (e.g. "nathan manages flair") |
+| `bootstrap` | Get session-start context: soul + recent memories + predicted-relevant context |
+| `soul_set` | Set a personality/project/standards entry — included in every bootstrap |
+| `soul_get` | Get a soul entry |
+| `flair_workspace_set` | Set your agent's current workspace state (ref/branch, phase, task) in the Office Space |
+| `flair_orgevent` | Publish an org-wide coordination event (claim/release/status) to the Office Space |
+
+Writes are scoped per-agent (your `FLAIR_AGENT_ID`) and enforced by Flair's server, not by client convention — you can't write as another agent. Reads are more open by design: any agent on the same Flair instance can read any other agent's non-private memories (open-within-org read; see [SECURITY.md](../SECURITY.md)). Mark a memory `visibility: private` to keep it owner-only.
+
+---
+
+## Configuration reference
+
+| Env var | Default | Notes |
+|---|---|---|
+| `FLAIR_AGENT_ID` | (none — required) | Must match `flair agent add <id>` |
+| `FLAIR_URL` | `http://127.0.0.1:19926` | Override for remote Flair instances |
+| `FLAIR_KEY_PATH` | `~/.flair/keys/<agent>.key` | Ed25519 PKCS8 key — created by `flair agent add` |
+
+The MCP server has no client-side flags beyond these env vars; everything else (timeouts, dedup thresholds, error classification) is opinionated defaults from the underlying [`@tpsdev-ai/flair-client`](../packages/flair-client) package.
+
+---
+
+## What about Hermes (Nous Research)?
+
+Hermes uses its own Python-native `MemoryProvider` ABC instead of MCP. It has its own Flair integration in [`packages/hermes-flair/`](../packages/hermes-flair). Same backend, same agent isolation, different plug shape.
+
+Future MCP-capable agent CLIs (and there are more landing every month) will work out of the box with the MCP server above — no per-framework adapter required from us.
+
+---
+
+## Troubleshooting
+
+**"FLAIR_AGENT_ID is required" on startup.** Set it in the MCP server's `env` block (per snippets above). The CLI's own env doesn't propagate to the spawned MCP subprocess unless declared.
+
+**"connection_error: could not reach Flair at http://127.0.0.1:19926".** The Flair server isn't running. Run `flair status` to check; `flair start` to bring it up.
+
+**"auth_error: …" on every call.** The agent identity doesn't match a registered key. Re-run `flair agent add <id>` (idempotent on re-add — won't lose existing memories).
+
+**Tool calls succeed but the agent doesn't see results in subsequent turns.** Check that the CLI is actually invoking `bootstrap` at session start — most CLIs need an explicit prompt nudge ("call the bootstrap tool now") on first use. Subsequent turns should pick up automatically once the CLI sees the schema.
+
+For deeper issues see [`troubleshooting.md`](troubleshooting.md) and the [`@tpsdev-ai/flair-mcp` repo](https://github.com/tpsdev-ai/flair/tree/main/packages/flair-mcp).

package/docs/n8n-management.md

@@ -0,0 +1,142 @@
+# n8n Workflow Management
+
+Programmatic activation/deactivation of n8n workflows — the approach we use for ops automation.
+
+## The Problem
+
+Direct SQLite edits to `workflow_entity.active` (or using `n8n update:workflow` while n8n is running) don't re-register schedule triggers in the in-memory scheduler. The schedule simply stops firing. Only the v1 public API's `POST /api/v1/workflows/:id/activate` (or flipping Active in the UI) properly registers the trigger.
+
+**Root cause**: n8n tracks activation via `activeVersionId`, not the `active` boolean alone. The `activeWorkflowManager` in-memory scheduler only picks up workflows where `activeVersionId IS NOT NULL`. Direct SQLite edits that only set `active=1` without setting `activeVersionId` will not be picked up even on restart.
+
+## Recommended Approach: v1 Public API (live instance)
+
+The **v1 public API** is the correct tool for managing workflows on a **running** n8n instance. It updates the DB AND calls the in-memory `ActiveWorkflowManager.add()` to register triggers immediately — no restart needed.
+
+### Endpoints
+
+| Action | Method | Endpoint | Body |
+|---|---|---|---|
+| Activate | `POST` | `/api/v1/workflows/:id/activate` | `{}` or `{"versionId": "..."}` |
+| Deactivate | `POST` | `/api/v1/workflows/:id/deactivate` | (none) |
+| List | `GET` | `/api/v1/workflows` | — |
+| Get one | `GET` | `/api/v1/workflows/:id` | — |
+
+### Authentication
+
+All v1 API calls require `X-N8N-API-KEY` header with a valid API key (see [API Key Generation](#api-key-generation) below).
+
+### Examples
+
+```bash
+# Activate workflow
+curl -X POST "http://127.0.0.1:5678/api/v1/workflows/$WORKFLOW_ID/activate" \
+  -H "X-N8N-API-KEY: $N8N_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{}'
+
+# Deactivate workflow
+curl -X POST "http://127.0.0.1:5678/api/v1/workflows/$WORKFLOW_ID/deactivate" \
+  -H "X-N8N-API-KEY: $N8N_API_KEY"
+
+# Check if workflow is active
+curl -s "http://127.0.0.1:5678/api/v1/workflows/$WORKFLOW_ID" \
+  -H "X-N8N-API-KEY: $N8N_API_KEY" | python3 -c "import json,sys; print(json.load(sys.stdin)['active'])"
+```
+
+See `scripts/n8n/activate-workflow.sh` for a reusable wrapper.
+
+## Why PATCH Doesn't Work
+
+n8n's v1 API docs mention `PATCH /api/v1/workflows/:id` with `{ "active": true }`. **This returns 405 Method Not Allowed on n8n 1.123.38.** The documented activation endpoints are `POST /api/v1/workflows/:id/activate` and `POST /api/v1/workflows/:id/deactivate`.
+
+## Alternative Approaches
+
+### Approach 2: CLI when n8n is stopped
+
+The `n8n update:workflow` CLI command works when n8n is **not running**. It updates both `active` and `activeVersionId` in the DB. On the next `n8n start`, `ActiveWorkflowManager.init()` reads `getAllActiveIds()` and registers all workflows with non-null `activeVersionId`.
+
+```bash
+# Stop n8n
+launchctl stop ai.tpsdev.n8n
+
+# Activate/deactivate via CLI
+N8N_PATH="/opt/homebrew/opt/node@24/bin" npx n8n@1.123.38 update:workflow --id=$WORKFLOW_ID --active=true
+# or
+N8N_PATH="/opt/homebrew/opt/node@24/bin" npx n8n@1.123.38 update:workflow --id=$WORKFLOW_ID --active=false
+
+# Start n8n
+launchctl start ai.tpsdev.n8n
+```
+
+**Caveats**:
+- `update:workflow` is deprecated (n8n v2 will replace it with `publish:workflow`/`unpublish:workflow`)
+- Requires a full stop/start cycle (downtime for all workflows)
+- `npx` needs node@24 (`/opt/homebrew/opt/node@24/bin/node`)
+
+### Approach 3: Internal REST API (editor UI)
+
+The `/rest/workflows/:id/activate` endpoint is what the editor UI uses. It requires session-based auth (cookie from `/rest/login`), which needs the admin password. Not practical for automation without storing credentials.
+
+```bash
+# Requires session cookie from /rest/login
+curl -X POST "http://127.0.0.1:5678/rest/workflows/$WORKFLOW_ID/activate" \
+  -b "fern-uid=...; n8n.session=..."
+```
+
+**Not recommended** for ops automation — session cookies expire and the password is a higher-value secret than an API key.
+
+## API Key Generation
+
+The v1 API key is a JWT signed with a secret derived from the encryption key. To create one programmatically:
+
+```javascript
+const crypto = require('crypto');
+const jwt = require('jsonwebtoken');
+const fs = require('fs');
+
+// Read encryption key from n8n config
+const config = JSON.parse(fs.readFileSync(process.env.HOME + '/.n8n/config', 'utf8'));
+const encKey = config.encryptionKey;
+
+// Derive JWT secret: SHA256 of every-other-character of encryption key
+let baseKey = '';
+for (let i = 0; i < encKey.length; i += 2) {
+  baseKey += encKey[i];
+}
+const jwtSecret = crypto.createHash('sha256').update(baseKey).digest('hex');
+
+// Sign JWT with user's ID (from `user` table in SQLite)
+const userId = '<user-uuid-from-sqlite>'; // e.g., 'a6ce7ac9-ef6d-4157-835a-4b0f01dc788a'
+const apiKey = jwt.sign(
+  { sub: userId, iss: 'n8n', aud: 'public-api' },
+  jwtSecret
+);
+
+// Store the returned key in the user_api_keys table so it persists
+
+console.log('API key:', apiKey);
+```
+
+Once stored in the DB, the key is valid until deleted. No expiration by default.
+
+**Security note**: The encryption key is needed to derive the JWT secret. This is the same key used to decrypt workflow credentials. If the encryption key is compromised, so are the credentials. Keep it scoped to the n8n user.
+
+## Why Direct SQLite Edits Don't Work
+
+The `workflow_entity` table has two activation fields:
+- `active` (boolean): UI flag
+- `activeVersionId` (varchar): points to the `workflow_history` record that defines the active version
+
+The `ActiveWorkflowManager` only considers workflows where `activeVersionId IS NOT NULL`. If you only flip `active=1` without setting `activeVersionId`, n8n never picks up the workflow — not on restart, not on refresh.
+
+Even with both fields set correctly, a live n8n instance has an in-memory scheduler that doesn't re-read the DB. Only the v1 API (or UI toggle) calls `activeWorkflowManager.add()` to register the trigger in-memory.
+
+## Quick Reference
+
+| Scenario | Method | Restart needed? |
+|---|---|---|
+| Activate on running n8n | `POST /api/v1/workflows/:id/activate` | No |
+| Deactivate on running n8n | `POST /api/v1/workflows/:id/deactivate` | No |
+| Activate when stopped | `n8n update:workflow --id=X --active=true` | Yes |
+| Direct DB edit (active + activeVersionId) | SQLite `UPDATE` | Yes, on restart |
+| Direct DB edit (active only) | SQLite `UPDATE` | **Won't work** — needs activeVersionId too |