* [docs] Fix Cursor MCP connection — use native url field, not mcp-remote

mcp-remote@latest now attempts OAuth client registration before sending
custom headers, which breaks against Open Brain's simple key-based auth.
Cursor supports remote MCP servers natively via the url field, so
mcp-remote is unnecessary.

Changes:
- Add dedicated Cursor section to getting-started guide (7.5) and
  remote-mcp primitive with native url config
- Update mcp-remote examples to pass key via ?key= query parameter
  instead of --header to avoid OAuth discovery issues
- Clarify x-brain-key (core) vs x-access-key (extensions) in
  troubleshooting guides

Made-with: Cursor

* [primitives] Bring remote MCP docs in line with repo format

---------

Co-authored-by: Jonathan Edwards <justfinethanku@gmail.com>

backfill.mjs previously tolerated integer-style NateBJones-Projects#123 parent refs when no
UUIDs were present, writing them into derived_from. On a canonical UUID
install trace_provenance and find_derivatives cast every element to
::uuid at query time, so those rows would explode later with 22P02
invalid input syntax. Silently writing unusable data is worse than
failing up front.

parseParentIds now throws loudly if any integer ref is detected, naming
the offending row, the sample refs, and why we refuse. The main loop
catches the throw per-row, logs a parse error reason, and still flips
derivation_layer='derived' on the row so operators can see the flag and
re-run with --force after fixing the artifact.

Update the README ID Type Note so BIGINT-fork users know this backfill
path is UUID-only and they must repopulate derived_from themselves.

* [docs] Fix Cursor MCP connection — use native url field, not mcp-remote

mcp-remote@latest now attempts OAuth client registration before sending
custom headers, which breaks against Open Brain's simple key-based auth.
Cursor supports remote MCP servers natively via the url field, so
mcp-remote is unnecessary.

Changes:
- Add dedicated Cursor section to getting-started guide (7.5) and
  remote-mcp primitive with native url config
- Update mcp-remote examples to pass key via ?key= query parameter
  instead of --header to avoid OAuth discovery issues
- Clarify x-brain-key (core) vs x-access-key (extensions) in
  troubleshooting guides

Made-with: Cursor

* [primitives] Bring remote MCP docs in line with repo format

---------

Co-authored-by: Jonathan Edwards <justfinethanku@gmail.com>

* [schemas] Provenance chains columns and helpers

Adds derived_from, derivation_method, derivation_layer, supersedes to public.thoughts plus trace_provenance and find_derivatives helper SQL. Idempotent, with rollback documented.

* [recipes] Provenance chains pipeline — backfill, eval, MCP tools

Scripts and tool handlers that operate on the provenance columns: backfill existing pointer/derived thoughts, nightly quality eval, and trace/find MCP tools for reasoning queries.

* [schemas] Fix REVIEW-CODEX-P1-2: service-role-only GRANT on provenance RPCs

SECURITY DEFINER helpers trace_provenance and find_derivatives were granted
to authenticated, so any signed-in Supabase user could call them via
PostgREST and bypass the edge-function access key. Restrict EXECUTE to
service_role only (revoke from authenticated and PUBLIC) so the edge
function is the sole caller.

Also drop the client-supplied p_exclude_restricted parameter from
find_derivatives — a caller could pass false and unmask restricted rows.
Restricted rows are now unconditionally hidden. DROP FUNCTION of the old
3-arg signature runs before CREATE OR REPLACE so the migration stays
re-runnable.

* [schemas] Fix CR-01: read sensitivity_tier/source_type/type from metadata, not columns

The canonical public.thoughts table (docs/01-getting-started.md) only
defines id, content, embedding, metadata, created_at, updated_at, and
content_fingerprint. The helpers were reading t.sensitivity_tier,
t.source_type, and t.type as top-level columns, which do not exist on a
stock OB1 install — the two CREATE OR REPLACE FUNCTION blocks failed with
'column does not exist' and left the migration half-applied.

Change both helpers to read those three fields via metadata->>'…'. The
RETURNS TABLE signatures keep the same columns so callers do not change.
Document the canonical-schema contract and the RLS behaviour (row-level,
not column-level) in the schema README.

* [recipes] Fix REVIEW-CODEX-P1-3: reject integer refs in UUID backfill

backfill.mjs previously tolerated integer-style #123 parent refs when no
UUIDs were present, writing them into derived_from. On a canonical UUID
install trace_provenance and find_derivatives cast every element to
::uuid at query time, so those rows would explode later with 22P02
invalid input syntax. Silently writing unusable data is worse than
failing up front.

parseParentIds now throws loudly if any integer ref is detected, naming
the offending row, the sample refs, and why we refuse. The main loop
catches the throw per-row, logs a parse error reason, and still flips
derivation_layer='derived' on the row so operators can see the flag and
re-run with --force after fixing the artifact.

Update the README ID Type Note so BIGINT-fork users know this backfill
path is UUID-only and they must repopulate derived_from themselves.

* [schemas] Fix WR-02: UUID regex constraint on derived_from elements

Element shape was previously validated only in application code. A bad
insert (integer, object, or non-UUID string) would pass the existing
'is JSONB array' check and only fail later inside trace_provenance with
22P02 invalid input syntax for uuid, with no pointer to the offending
row. Add thoughts_derived_from_uuid_elements_check so every element is
asserted to be an RFC 4122 UUID string at write time, and the
constraint name makes the bad row easy to locate.

Update the rollback block to drop the new constraint.

* [recipes] Fix REVIEW-CODEX-P2: inline MCP envelopes, no missing helpers

mcp-tools.ts previously called toolSuccess(...) and toolFailure(...)
helpers that do not exist in the canonical server/index.ts. Pasting the
snippet as documented produced compile errors.

Replace every return with the literal envelope shape
  { content: [{ type: 'text', text: ... }] }
(plus isError: true on failure paths) so the snippet matches the
canonical server patterns and drops in clean. Also drop the
exclude_restricted input on find_derivatives because the SQL RPC no
longer accepts it (see P1-2 fix) — the filter is hardcoded server-side.

README updated to reflect the new signature and sensitivity-enforcement
contract.

* [recipes] Fix WR-01/WR-06: SUPABASE_* canonical, OPEN_BRAIN_* fallback

Every other OB1 recipe (instagram-import, grok-export-import, etc.) uses
SUPABASE_URL / SUPABASE_SERVICE_ROLE_KEY. This recipe introduced the
novel OPEN_BRAIN_URL / OPEN_BRAIN_SERVICE_KEY pair, so users with an
existing .env hit 'missing env' even though their canonical credentials
were set.

backfill.mjs and eval.mjs now read SUPABASE_* first and fall back to
OPEN_BRAIN_* with a one-time deprecation warning. The grader key gains
the same pattern — OPENROUTER_API_KEY preferred, ANTHROPIC_API_KEY
accepted with a warning that it must be an OpenRouter-compatible token
for the openrouter grader to authenticate.

eval.mjs also fails fast when the openrouter grader is selected without
a key (WR-06), before doing the Supabase candidate/parent fetches that
would otherwise burn 201+ round-trips on a 200-row run.

README credential tracker and export block updated to canonical names.

* [recipes] Fix REVIEW-CODEX-P3: remove unused node:path import

path was imported but never referenced in eval.mjs.

* [schemas] Fix REVIEW-CODEX-2-P1: drop subquery CHECK; UUID validation in app layer

* [recipes] Fix REVIEW-CODEX-2-P1: read source_type/type from metadata via PostgREST JSON syntax

* [recipes] Fix REVIEW-CODEX-2-P2: mirror backfill provenance into metadata for stock RPC compat

* [schemas] Add merge_thought_provenance_metadata RPC for race-free metadata mirror

* [recipes] Fix REVIEW-CODEX-3-P1: backfill uses RPC instead of GET+PATCH to avoid race with eval

* [docs] Explain race-free metadata mirror in provenance READMEs

* [schemas] Add merge_thought_eval_metadata RPC for race-free eval writes

* [recipes] Fix REVIEW-CODEX-4-P1: eval.mjs uses RPC instead of GET+PATCH to close reverse race

* [recipes] Fix REVIEW-CODEX-4-P2: document and handle backfill half-migration recovery

* [schemas] Fix REVIEW-CODEX-5-P2: merge_thought_*_metadata RPCs raise on zero rows

* [recipes] Fix REVIEW-CODEX-5-P2: eval apply-scores surfaces missing thoughts as errors

* [recipes] Fix REVIEW-CODEX-5-P2: backfill exits non-zero on half-migrated rows

* [recipes] Fix REVIEW-CODEX-6-P1: trace_provenance returns cycle stubs instead of crashing

* [recipes] Fix REVIEW-CODEX-6-P2: eval.mjs exits non-zero on malformed lines and row errors

* [recipes] Fix REVIEW-CODEX-6-P3: backfill distinguishes deleted rows from half-migrated

* [recipes] Fix REVIEW-CODEX-7-P1: correct trace_provenance edge direction in tree rebuild

* [recipes] Fix REVIEW-CODEX-7-P2: backfill exits non-zero on provenance parse errors

* [recipes] Fix REVIEW-CODEX-8-P2: use per-row depth in trace_provenance, not canonical

* [recipes] Fix REVIEW-CODEX-8: dry-run parse-error warning qualifies 'would have'

* [recipes] Fix REVIEW-CODEX-9-P2: over-fetch by one to detect trace_provenance truncation precisely

* [recipes] Fix REVIEW-CODEX-9-P2: paginate fetchCandidates to survive eval backlogs

* [recipes] Fix REVIEW-CODEX-10-P2: keyset pagination on (created_at, id) for stable fetchCandidates

* [recipes] Fix REVIEW-CODEX-11-P1: quote keyset cursor values to escape PostgREST reserved dots

* [provenance] Tidy docs for lint and current paths

---------

Co-authored-by: Jonathan Edwards <justfinethanku@gmail.com>

…s-Projects#207)

* [schemas] Provenance chains columns and helpers

Adds derived_from, derivation_method, derivation_layer, supersedes to public.thoughts plus trace_provenance and find_derivatives helper SQL. Idempotent, with rollback documented.

* [recipes] Provenance chains pipeline — backfill, eval, MCP tools

Scripts and tool handlers that operate on the provenance columns: backfill existing pointer/derived thoughts, nightly quality eval, and trace/find MCP tools for reasoning queries.

* [schemas] Fix REVIEW-CODEX-P1-2: service-role-only GRANT on provenance RPCs

SECURITY DEFINER helpers trace_provenance and find_derivatives were granted
to authenticated, so any signed-in Supabase user could call them via
PostgREST and bypass the edge-function access key. Restrict EXECUTE to
service_role only (revoke from authenticated and PUBLIC) so the edge
function is the sole caller.

Also drop the client-supplied p_exclude_restricted parameter from
find_derivatives — a caller could pass false and unmask restricted rows.
Restricted rows are now unconditionally hidden. DROP FUNCTION of the old
3-arg signature runs before CREATE OR REPLACE so the migration stays
re-runnable.

* [schemas] Fix CR-01: read sensitivity_tier/source_type/type from metadata, not columns

The canonical public.thoughts table (docs/01-getting-started.md) only
defines id, content, embedding, metadata, created_at, updated_at, and
content_fingerprint. The helpers were reading t.sensitivity_tier,
t.source_type, and t.type as top-level columns, which do not exist on a
stock OB1 install — the two CREATE OR REPLACE FUNCTION blocks failed with
'column does not exist' and left the migration half-applied.

Change both helpers to read those three fields via metadata->>'…'. The
RETURNS TABLE signatures keep the same columns so callers do not change.
Document the canonical-schema contract and the RLS behaviour (row-level,
not column-level) in the schema README.

* [recipes] Fix REVIEW-CODEX-P1-3: reject integer refs in UUID backfill

backfill.mjs previously tolerated integer-style NateBJones-Projects#123 parent refs when no
UUIDs were present, writing them into derived_from. On a canonical UUID
install trace_provenance and find_derivatives cast every element to
::uuid at query time, so those rows would explode later with 22P02
invalid input syntax. Silently writing unusable data is worse than
failing up front.

parseParentIds now throws loudly if any integer ref is detected, naming
the offending row, the sample refs, and why we refuse. The main loop
catches the throw per-row, logs a parse error reason, and still flips
derivation_layer='derived' on the row so operators can see the flag and
re-run with --force after fixing the artifact.

Update the README ID Type Note so BIGINT-fork users know this backfill
path is UUID-only and they must repopulate derived_from themselves.

* [schemas] Fix WR-02: UUID regex constraint on derived_from elements

Element shape was previously validated only in application code. A bad
insert (integer, object, or non-UUID string) would pass the existing
'is JSONB array' check and only fail later inside trace_provenance with
22P02 invalid input syntax for uuid, with no pointer to the offending
row. Add thoughts_derived_from_uuid_elements_check so every element is
asserted to be an RFC 4122 UUID string at write time, and the
constraint name makes the bad row easy to locate.

Update the rollback block to drop the new constraint.

* [recipes] Fix REVIEW-CODEX-P2: inline MCP envelopes, no missing helpers

mcp-tools.ts previously called toolSuccess(...) and toolFailure(...)
helpers that do not exist in the canonical server/index.ts. Pasting the
snippet as documented produced compile errors.

Replace every return with the literal envelope shape
  { content: [{ type: 'text', text: ... }] }
(plus isError: true on failure paths) so the snippet matches the
canonical server patterns and drops in clean. Also drop the
exclude_restricted input on find_derivatives because the SQL RPC no
longer accepts it (see P1-2 fix) — the filter is hardcoded server-side.

README updated to reflect the new signature and sensitivity-enforcement
contract.

* [recipes] Fix WR-01/WR-06: SUPABASE_* canonical, OPEN_BRAIN_* fallback

Every other OB1 recipe (instagram-import, grok-export-import, etc.) uses
SUPABASE_URL / SUPABASE_SERVICE_ROLE_KEY. This recipe introduced the
novel OPEN_BRAIN_URL / OPEN_BRAIN_SERVICE_KEY pair, so users with an
existing .env hit 'missing env' even though their canonical credentials
were set.

backfill.mjs and eval.mjs now read SUPABASE_* first and fall back to
OPEN_BRAIN_* with a one-time deprecation warning. The grader key gains
the same pattern — OPENROUTER_API_KEY preferred, ANTHROPIC_API_KEY
accepted with a warning that it must be an OpenRouter-compatible token
for the openrouter grader to authenticate.

eval.mjs also fails fast when the openrouter grader is selected without
a key (WR-06), before doing the Supabase candidate/parent fetches that
would otherwise burn 201+ round-trips on a 200-row run.

README credential tracker and export block updated to canonical names.

* [recipes] Fix REVIEW-CODEX-P3: remove unused node:path import

path was imported but never referenced in eval.mjs.

* [schemas] Fix REVIEW-CODEX-2-P1: drop subquery CHECK; UUID validation in app layer

* [recipes] Fix REVIEW-CODEX-2-P1: read source_type/type from metadata via PostgREST JSON syntax

* [recipes] Fix REVIEW-CODEX-2-P2: mirror backfill provenance into metadata for stock RPC compat

* [schemas] Add merge_thought_provenance_metadata RPC for race-free metadata mirror

* [recipes] Fix REVIEW-CODEX-3-P1: backfill uses RPC instead of GET+PATCH to avoid race with eval

* [docs] Explain race-free metadata mirror in provenance READMEs

* [schemas] Add merge_thought_eval_metadata RPC for race-free eval writes

* [recipes] Fix REVIEW-CODEX-4-P1: eval.mjs uses RPC instead of GET+PATCH to close reverse race

* [recipes] Fix REVIEW-CODEX-4-P2: document and handle backfill half-migration recovery

* [schemas] Fix REVIEW-CODEX-5-P2: merge_thought_*_metadata RPCs raise on zero rows

* [recipes] Fix REVIEW-CODEX-5-P2: eval apply-scores surfaces missing thoughts as errors

* [recipes] Fix REVIEW-CODEX-5-P2: backfill exits non-zero on half-migrated rows

* [recipes] Fix REVIEW-CODEX-6-P1: trace_provenance returns cycle stubs instead of crashing

* [recipes] Fix REVIEW-CODEX-6-P2: eval.mjs exits non-zero on malformed lines and row errors

* [recipes] Fix REVIEW-CODEX-6-P3: backfill distinguishes deleted rows from half-migrated

* [recipes] Fix REVIEW-CODEX-7-P1: correct trace_provenance edge direction in tree rebuild

* [recipes] Fix REVIEW-CODEX-7-P2: backfill exits non-zero on provenance parse errors

* [recipes] Fix REVIEW-CODEX-8-P2: use per-row depth in trace_provenance, not canonical

* [recipes] Fix REVIEW-CODEX-8: dry-run parse-error warning qualifies 'would have'

* [recipes] Fix REVIEW-CODEX-9-P2: over-fetch by one to detect trace_provenance truncation precisely

* [recipes] Fix REVIEW-CODEX-9-P2: paginate fetchCandidates to survive eval backlogs

* [recipes] Fix REVIEW-CODEX-10-P2: keyset pagination on (created_at, id) for stable fetchCandidates

* [recipes] Fix REVIEW-CODEX-11-P1: quote keyset cursor values to escape PostgREST reserved dots

* [provenance] Tidy docs for lint and current paths

---------

Co-authored-by: Jonathan Edwards <justfinethanku@gmail.com>