sovereignty-scan-mcp: Instructions file for Claude Code

CLAUDE.md — @kajaril/sovereignty-scan-mcp

This file is the constitution for Claude Code working in this repo. Read it before any non-trivial change.

This is a template. Copy to the repo root as CLAUDE.md at milestone M1. Update the "Repo state" section as the build progresses. Everything above that section is locked and should not be edited without a corresponding decision update in kajaril-decisions-addendum-wk0.md or this plan.

---

What kajaril is

A one-person studio out of Cairo. Tools, agents, and platforms — built quietly, finished properly. This repo is the first published MCP product: a vendor sovereignty scanner for EU AI Act compliance.

The product is an artifact in a credential layer. Code shipped here will be read by DPO buyers, regulators, and audit agents. Every decision in this codebase is on the record.

Required reading before structural changes

Three documents are canonical. Read them, in order, before any change that touches architecture, the data model, the seed, or any locked decision:

1. kajaril-source-of-truth.md — strategy, wedge, stack, roadmap
2. kajaril-decisions-addendum-wk0.md — entity-level locked decisions #11–#18 (overrides §2.2 and §4.2 of the source-of-truth)
3. sovereignty-scan-mcp-plan.md — Week 1 build plan + locked decisions #1–#7 specific to this MCP

These files live in the kajaril Entity folder, not in this repo. The build plan is the spec. Deviating from any locked decision (#1–#7 in the build plan, #11–#18 in the addendum) requires stopping, asking, and recording the new decision in writing before code changes.

Locked decisions for this repo

These are not negotiable. If implementation reveals a reason one should change, stop and ask — do not adapt the code to a different decision silently.

1. Database split — Free-tier worker binds only to sovereignty_db_free. Never adds a binding to sovereignty_db_paid for any reason.
2. scan_stack cap — Hard limit of 50 providers per call. Returns INPUT_TOO_LARGE over.
3. suggest_eu_alternatives algorithm — Deterministic. The four-step logic in the build plan §Decisions is the spec; do not introduce ranking heuristics.
4. Error envelope — Every failure path returns {error: {code, message, retryable, details}}. Codes are locked at v0.1.0; do not add new codes without updating types.ts first and bumping the contract.
5. KV cache key strategy — Per-provider keys (provider:{id}, category:{name}:ids, all:provider_ids, meta:last_refresh). Do not switch to a snapshot-blob pattern.
6. Provider data updates — seed.ts is the source of truth. D1 is derived. All updates are commits to seed.ts, reviewed via PR, then idempotent reseed (INSERT ... ON CONFLICT DO UPDATE). Writing SQL UPDATE directly against live D1 is prohibited — it leaves no audit trail.
7. License + metadata — MIT. package.json author, repository, homepage, bugs are locked. LICENSE file at repo root.