docs: rewrite README for a first-time visitor, relocate the detail into docs/

[laugiov]

Pipeline: chore
Spec: n/a — documentation only
Gates: G1 (content review) approved by the maintainer before the commit; no architecture review — no layer is touched
Deploy-impact: none — README.md and docs/.md only; no infra/docker/**, no docker-compose.yml, no .env.dist

Summary

The README read as complete product documentation: 2409 words, 367 lines. The reader arriving from Hacker News gives it about 30 seconds and needs four things — what it does, why it is credible, how to see it running with zero setup, and an honest statement of limits. Everything else belonged in docs/.

README.md is now 704 words / 124 lines. Nothing is deleted: every removed block was integrated into the file in docs/ that already covers its topic, or into one of two new files.

No production, performance or effectiveness figures appear anywhere in the new README — no conversation counts, no IOC counts, no observation window, no precision or accuracy numbers, no cost figures. Figures found in docs/ while working were left where they were.

Changes

• README.md rewritten in this order: logo + tagline + 4 badges (CI, codecov, License, Live demo — Status, Stack, Docker, STIX, PRs Welcome and Website dropped), the screenshots GIF unchanged, the two-sentence description of the gap it fills, the Black Hat USA 2026 line, then the "Try it" section (hosted demo with its credentials, and make demo-up with the explicit "no API key, no account, no mailbox"), how it works, what it produces, quick start, limitations, security and ethics, license / contributing / contact. The reader learns what the project is before reaching the demo credentials.
• New "Limitations" section, written from the caveats that were scattered through the old README: email-only and inbound-only, not a control, only OpenCTI verified end to end, no published metric for the TTP module, read-only review queue and manual campaign attribution, output quality depends on the model, seeded demo data, single-host deployment, operator-owned legality. Qualitative, no numbers.
• Project Status table removed. Every row said "Complete", which reads as marketing to this audience; docs/06_roadmap.md already covers the same ground honestly and is linked instead.
• New docs/README.md — the documentation entry point, carrying the index table that used to sit in the README, grouped (start here / concepts / intelligence / integration / operations) and extended with the guides the old table omitted.
• New docs/27_ttp_intelligence.md — the TTP module's architectural description, including the note that no published metric applies to it. docs/26_reading_the_ttp_screens.md was read first: it is a UI field guide, so the architecture did not belong there.
• Punctuation: the README uses double hyphens (--), not em dashes, as the previous README did.

Where each removed block landed:

Removed from README	Destination
Scammer TTP intelligence section, in full, with the metrics note	docs/27_ttp_intelligence.md (new)
STIX evidence detail (sighting fields), ATT&CK mapping, x_scambuster_actor engagement metrics, OpenCTI bundle validation; psych profiling and fuzzy clustering	docs/21_threat_actor_profiling.md
Analyst feedback loop	docs/24_analyst_feedback.md (already covered; cross-linked into the threat-actor intelligence stack)
Full IOC contextual enrichment description	docs/02_value_proposition.md, under Hybrid IOC Extraction
Multilingual design rationale	docs/25_prompt_customization.md, new "Multilingual by design" section
Tech stack table, project structure tree, data sovereignty note, human delay simulation	docs/03_high_level_architecture.md
LLM provider table, default credentials, production hardening, by-hand vs AI-agent deploy note	docs/QUICKSTART.md
Documentation index table	docs/README.md (new)
Project Status table	already covered by docs/06_roadmap.md

Duplicated statements were reconciled into each file's existing structure rather than appended verbatim.

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Refactoring (no functional change)
• Documentation update
• Infrastructure / CI change

Checklist

• make test passes — n/a, no application code changed
• make stan passes — n/a, no PHP changed
• make cs-fixer applied and left the worktree unchanged — n/a, no PHP changed
• New code has tests — n/a, documentation only
• Documentation updated if needed
• No secrets or credentials in the code — the demo credentials, licence, demo URLs and commands are unchanged from the previous README
• Follows DDD architecture — n/a, no Domain, Application, Infrastructure or UI code touched, no migration, no port interface

Factory gates

• Every commit and task cites a requirement id — n/a, chore pipeline, no spec
• Gate reports linked in the Gates: line above — G1 was a content review taken directly with the maintainer, who approved the full README text and the relocation map before the commit
• Escalation triggers listed — none fired: the diff is confined to README.md and docs/*.md, no sensitive path is touched
• Reproduction or exploit test committed before the fix — n/a, not a bug or security PR

Verification

• README.md: 704 words, 124 lines (was 2409 / 367).
• Every internal link and heading anchor in the nine changed files was resolved against the filesystem; the only non-filesystem link is ../../issues, GitHub's relative issues path, carried over unchanged.
• ../README.md#contact in docs/06_roadmap.md and docs/07_faq.md still resolves — the ## Contact heading is kept, and those two are the only links into a README anchor anywhere in the repository.
• Every relocated block was checked to be present at its destination, and every file under docs/ appears in the new docs/README.md index.
• The capability counts kept in the README match the code: 13 scam types (ScamTypeFixtures seeds 14 codes, of which UNKNOWN is the fallback) and 36 IOC types.
• No emoji, no marketing adjectives, licence / credentials / demo URLs / commands / GIF and logo paths unchanged.