Welcome to the MARS mandate

Living document. Last updated 2026-07-28. Latest version at mars_feed/WELCOME_TO_THE_MANDATE.md (source of truth) and kee.staticpipe.com/mars/welcome-to-the-mandate.html (shareable render).

For: teams that have been running independently and now need to integrate with the MARS platform. If your work touches a company, person, deal, filing, or any structured entity — this doc applies to you.

How to read this: the contracts section is non-negotiable. Every new vertical accepts them by sending the acceptance note on team-mail. Everything else is context you need to be productive.

1. What MARS is now

MARS is the shared platform underneath every kscope data product. Verticals (reit / bios / flare / credit / lp_data / insurance / signals / prospects / insider / donor / sedar / sections / crown / ...) all write to the same canonical entity substrate under mars.*_v2 in Postgres.

• One companies_v2. One canonical row per real company, UUID company_id. Every vertical writes here through a single mint API.
• One persons_v2. Same shape for real people.
• One investors_v2, institutions_v2, funds_v2, advisors_v2. Same shape for the other entity kinds.
• Deal / event tables are per-vertical (funding_deals_v2, merger_deals_v2, real_estate_deals_v2, private_credit_deals_v2, thermal_events_v2, form_4_transactions_v2, signals_v2, ...) but every row FKs back to the shared entity canonicals.

The moat is the entity graph across all verticals. Not any single vertical. The reason cross-vertical queries work — "who worked at Merrill now runs an RIA managing > $1B AUM," "was the target of this merger raised on private credit first," "insider sold days after Form D close" — is that every vertical writes to the same company_id / person_id.

2. The 10 platform contracts

Non-negotiable. Full text in mars_feed/MARS_PLATFORM_CONTRACTS.md. Summary:

1. Canonical company_id. Mint via mars_entity_mint HTTP API. Never mint into companies_v2 directly.
2. integrity_tier on every deal / event row. verified / vouched / warn. Consumers filter IN ('verified','vouched').
3. Standard sector taxonomy. Use the same industry buckets as funding_stage_mapping.py / industry_mapping.py.
4. Tier chain for LLM cost. Qwen first (~$0), Haiku or gpt-oss as escalation, Grok/Brave only for world knowledge. Detail below.
5. Own your *_v2 deal/event table. Namespaced (real_estate_deals_v2, credit_bankruptcy_filings_v2, etc.). Not on the shared canonicals.
6. Direct-to-v2. No detour through v1 Mongo. Every write goes to mars.*_v2 in Postgres.
7. Deterministic + LLM + audit trio. Deterministic checks first (regex, whitelist, name-match), LLM for the gray zone, audit script that spot-checks after landing.
8. Health email visibility. Your vertical writes to the daily 13:00 UTC health.py email. If it's broken, the health check must fire.
9. Team-mail communication. All cross-team coordination via s3://kscope-team-mail/{slug}/inbox/. No Slack, no direct email for coordination.
10. Documentation deliverables. Every vertical has a CONTRACT.md + SCHEMA.md + SOURCES.md + README.md + CLAUDE.md (ops guide). See bios_pipeline/ or reit_pipeline/ for the shape.

Full text: https://kee.staticpipe.com/mars/platform-contracts.html (source: mars_feed/MARS_PLATFORM_CONTRACTS.md).

How you accept: send an acceptance note from your team-mail slug to mars. That's the handshake.

3. Minting entities — MINTING_ENTITIES.md summary

The most common bug in the mars ecosystem is a vertical writing a duplicate entity because it didn't check for matches first. The MINTING_ENTITIES.md doctrine (in mars_feed/) covers all 5 canonical tables. Full details there; the 5-rule discipline:

1. Strong-ID match first. CIK, CRD, ticker, LinkedIn URL, ISIN. If a strong ID matches, USE THAT ROW. Never mint a duplicate.
2. Name-variant lookup. companies_v2.name_variants[] is populated with historical aliases (Facebook → Meta). Check GIN-indexed @> lookup BEFORE trigram match.
3. Name + candidate + Qwen verify. Trigram fuzzy match with pg_trgm, then Qwen classifier when candidates are close.
4. Sentinel filter at write. is_sentinel_name / is_role_not_name / is_placeholder_crd — never mint "Unknown Target" / "TBD" / "N/A" / "CEO" as a name.
5. Log every mint to identity_decisions_v2. Decision + methodology + metadata. Reversible.

Full text: https://kee.staticpipe.com/mars/minting-entities.html (source: mars_feed/MINTING_ENTITIES.md).

For persons specifically, see bios_pipeline/MINTING_PEOPLE.md — 10 persons-side rules with drop-in code.

Use the mint API, don't hand-write minting logic.

• HTTP: POST https://mint.staticpipe.com/companies (or /persons)
• Python: from mars_feed.mint import mars_entity_mint
• Same logic every time. Same guards. Same identity_decisions_v2 audit trail.

4. The Qwen / Brave / Grok line (2026-07 doctrine)

The rule: Qwen is reliable whenever the answer is IN THE TEXT you give it. Grok / Brave are only needed when the decision requires WORLD KNOWLEDGE.

Concretely:

The trap Qwen falls into: same-brand-different-vehicle. "Blackstone Real Estate Partners" vs "Blackstone Europe Real Estate" reads as the same to Qwen because both strings contain "Blackstone Real Estate." The answer requires WORLD KNOWLEDGE (which fund vehicle exists, which is a regional sub-fund) that isn't in the strings you passed.

Fix pattern: for entity resolution where only the NAME links two rows, use Grok-web OR the newer Brave+Qwen tier. Never Qwen alone.

Brave+Qwen tier chain (new 2026-07-28): 1. Brave Search API returns candidate URLs 2. Qwen reads the top-3 URL summaries to verify 3. ~20× cheaper than Grok-web for the same accuracy 4. Endpoint: via Inferno HTTP API — see ref-brave-qwen-replaces-grokweb memory or ask mars 5. Currently in bios B-17 calibration; wider rollout after that clears

5. Consumer contract — the 3 filters

Every consumer query MUST apply these 3 filters (or explicitly document why not):

WHERE integrity_tier IN ('verified','vouched')  -- not 'warn'
  AND amount_usd_converted IS NOT NULL           -- for FX comparability
  AND NOT is_placeholder                         -- on investors_v2 side

Additional performance notes:

• Use lower(col) LIKE lower(:pat), never ILIKE (130ms → 17ms; the trigram GIN doesn't kick in for ILIKE).
• Use WITH found AS MATERIALIZED (... LIMIT 1) to avoid the GIN+LIMIT-1 seq-scan trap on small tables.
• Person queries should hit bios_current_firm_v2, not persons_v2 directly (planner mis-estimates the methodology filter 38×).

6. Kbrain — Adrian's knowledge vault

URL: https://api-dev.kscope.io/kbrain/mcp (MCP endpoint).

What kbrain is for: durable reference. Entity models, source-of-truth documentation, doctrines, API contracts, concepts. Things that will still be true 6 months from now.

What kbrain is NOT for: transient state. Task lists. Progress trackers. Current-status pages. Things that decay and mislead future readers.

MARS's kbrain footprint: 6 notes live there today (created by mars on adrian's kbrain): - Projects/MARS.md — top-level project doc - Reference/MARS entity graph v2.md — the canonical shape - Reference/MARS data sources.md — where each vertical sources from - Reference/mars_entity_mint API.md — mint API contract - Concepts/MARS query patterns.md — consumer patterns - Concepts/Consumer contract filter.md — the 3-filter rule above

Sync obligation: when substrate / contract / sources / mint changes, mars updates kbrain. Contract change → kbrain edit within same session.

For your team: if you want your team's docs in kbrain, submit them via team-mail to mars — we'll seed on your behalf. Adrian owns the vault so all writes go through us.

7. Team-mail bus

The async coordination channel.

• Bucket: s3://kscope-team-mail/
• Your inbox: s3://kscope-team-mail/{your-slug}/inbox/
• Helper: mars_feed/teammsg.py — copy to your repo or use directly
• Send: python3 teammsg.py send {recipient-slug} "subject" --file body.md
• Read: aws s3 ls s3://kscope-team-mail/{your-slug}/inbox/ --recursive

Active slugs (2026-07-28): mars · mars-ui · futures · rss · bios · reit · credit · insurance · intl · lp · signals · prospects · insider · donor · flare · sedar · sections · inferno · crown · instagram · argos · power-sec.

Establishing a new slug: first inbound message to s3://kscope-team-mail/{slug}/inbox/ creates it.

8. New tools you should know about (2026-07)

• mars_entity_mint HTTP API — https://mint.staticpipe.com/companies and /persons. Standard minting with all 5 rules baked in. Accepts optional CIK / CRD / ticker / domain hints to speed up resolution.
• Inferno HTTP API — https://inferno.staticpipe.com/jobs. Batch Qwen at ~$0.0002/item. Auto-shard 100 items/shard. Body limit ~1MB (~5-6K items per submission).
• Brave Search API — via Inferno. Cheap entity-in-the-world resolution (see Qwen line above).
• merge_entities.py — atomic entity merger with dynamic FK discovery from pg_catalog. Handles all 5 canonicals + JSONB additive merge. Never write your own merge code.
• Weekly linkage sweep — mars-linkage-sweep.timer (Sun 09:00 UTC). 7 deterministic FK re-sweeps that catch write-time misses. Free.
• Refresh MV chain — mars-refresh-views.timer (daily 06:15 UTC). Add your MVs / serving tables via refresh_materialized_views.py.

9. Extraction traps to avoid (2026-07 learnings)

Things that have bitten us hard. If your vertical touches any of these patterns, read the corresponding memory / doctrine before shipping.

• Write-drop trap: LLM extracts a field, Python whitelist DROPS it before writing to Postgres. 10-day zero-coverage silent bite on valuation columns 07-27. Always grep for the write-path copy list when adding a field to an LLM prompt.
• JSONB additive-merge trap: merge_entities.py used COALESCE(keep, drop) on JSONB, silently dropping additive keys. Fixed 07-28. Any merge tool MUST handle JSONB additively.
• Franken-person taxonomy: placeholder-CRD (1234567), firm-CRD attributed to individual, common-name over-merge (John Smith 30 companies). See ref-franken-person-taxonomy memory. Fix in MINTING_PEOPLE Rule 1a + 2 + 3.
• Qwen fails fluently on world-knowledge: same-brand-different-vehicle is rife in PE / RE / infra. Use Grok-web or Brave+Qwen for entity-in- the-world tasks.
• Health check must detect a dead pipeline: internal consistency checks (MV vs its own base tables) stay green forever on a graph ingesting NOTHING. Check newest-row-age from SOURCE, not just from your MV. Bios check_ingest caught this class 07-14.
• Legacy substrate inheritance: when your vertical takes over legacy rows, retag doesn't surface them; the tier gate holds. But BEFORE backfilling bridges (person_work_history_v2 etc.), vet the legacy — linkages leak past the tier gate. See ref-legacy-substrate-inheritance-doctrine.
• nohup / setsid blocked here. Use run_in_background if you're scripting via Claude. If shell, use systemd.
• PyMuPDF not thread-safe. Use processes.
• Any INSERT INTO mars.*_v2 needs the sentinel guard. Every mint path. extract_2b_bios guarded, link_employers was NOT — re-leaked in a loop. Grep every INSERT.

10. Vertical status map (2026-07-28)

11. How to integrate — new-vertical checklist

1. Read this doc end to end.
2. Read mars_feed/MARS_PLATFORM_CONTRACTS.md in full.
3. Read mars_feed/MINTING_ENTITIES.md in full.
4. Send acceptance from your slug on team-mail bus to mars. Format: "we've read the mandate + contracts + minting doctrine; here's what we're doing; here's our proposed table shape; here's our target ship date."
5. Get pointed at existing substrate you'll write to — or scope a new *_v2 table under your slug's methodology tag prefix (e.g., power-sec-*).
6. Health check contract: your vertical adds a check_{vertical} function to mars_feed/health.py that fires on real signals (freshness, coverage, integrity_tier mix). Route it through the daily 13:00 UTC email.
7. Documentation: create {your_pipeline}/CONTRACT.md, SCHEMA.md, SOURCES.md, README.md, CLAUDE.md. Copy shape from reit_pipeline/ or bios_pipeline/.

12. Living document — how this updates

This doc is the running doctrine for platform-wide learnings. When something changes:

• Contract change → update MARS_PLATFORM_CONTRACTS.md + append to section 2 here.
• New extraction trap discovered → append to section 9.
• New tool shipped → append to section 8.
• New vertical goes LIVE → update section 10.
• New model / Qwen-line refinement → update section 4.
• Kbrain sync if section 6 changes.

The mars team maintains this doc. Contributions welcome — send an edit-suggestion on team-mail and we'll integrate.

Appendix — reading list order

If you're onboarding fresh, this is the order (all available as hosted HTML for teams without repo access):

1. This doc: kee.staticpipe.com/mars/welcome-to-the-mandate.html
2. Platform contracts: kee.staticpipe.com/mars/platform-contracts.html
3. Minting entities: kee.staticpipe.com/mars/minting-entities.html
4. bios_pipeline/MINTING_PEOPLE.md (if your vertical mints persons — ping bios team for hosted URL if needed)
5. mars_feed/mcp_specs/ (if you're a consumer)
6. mars_feed/PRODUCTION_READINESS_V2.md (if you're building a consumer product)

That's ~2 hours of reading. Everything else is available on team-mail or by asking mars directly.

— mars