CR-README-01: reposition README + PyPI to organisational intelligence

[quantamixsol]

What this changes

Repositions the public GitHub README and the PyPI package page away from EU-AI-Act-first governance toward persistent organisational intelligence.

Governance is re-ranked, never removed: it becomes the trust layer that makes the intelligence safe to act on, rather than the category headline.

Public port of private PR #341 (merged 2026-09-14, merge commit 06a2527a). Scoped to the four files this CR owns; content is byte-identical to private/master.

---

Positioning changes

	Before	After
Hero	"query your architecture, prove your AI's decisions" + "runtime governance for regulators"	"give your AI a memory of how your organisation actually works" — codebases, documents, policies, decisions, workflows
EU AI Act first mention	line 13 (first screen)	line 251 of 328
Moved up	—	model independence, MCP-first, the compounding advantage
Moved down	—	runtime attestation, cryptographic substrate, token economics
Compliance scope	EU AI Act only	EU AI Act + SOX/COSO (shipped x-sox pack) + ISO/IEC 42001 + GDPR claim limits + packs-as-data for NIST AI RMF / SOC 2 / HIPAA

The page now reads for a developer in San Francisco, Bangalore, Amsterdam, Singapore or Sydney who has no EU compliance requirement — while losing none of the regulated-market advantage.

---

ADR-MARKETING-001 is fully respected

tests/test_compliance/test_readme_snapshot_lock.py is a merge gate pinning public positioning. Every locked marker stays IN README.md — the EU AI Act–aligned shields.io badge, the literal Articles 6, 9, 12, 13, 14, 15, 25, 50 scope string, and both NOT-claims — relocated into the Regulated deployments section rather than deleted.

62/62 lock tests pass on this tree. No ADR amendment required.

---

Operational fixes (each defect reproduced before fixing)

1. PyPI served the wrong file. pyproject.toml pointed readme at README.md, so the concise README_PYPI.md never reached PyPI. Pointer switched. Verified in the built wheel's METADATA, not in source.

2. Broken quickstart command. Both READMEs published graq learn "<text>", which errors with No such command — learn is a Typer sub-app with no bare-string callback. Corrected to graq learn knowledge "<fact>", verified end-to-end on a cold project.

3. A second non-existent command. Both READMEs published graq lessons <domain>. That command does not exist; the real surface is graq learned. Caught by machine-diffing every README command against graq --help — it survived manual review.

4. Wrong counts.

   • MCP tools published as "76+" (README) and "74" (PyPI) → graq mcp tools --json reports 85 graq_ tools (+83 kogni_ aliases).
   • "14 backends" counted Azure OpenAI, which has no preset, no registry entry and no backend class → corrected to 13 named + custom HTTP.

5. Placeholder answers carried a confidence score. With no LLM configured, MockBackend emitted Confidence: NN% beside "[NO LLM CONFIGURED … placeholder …]" — indistinguishable from a governed answer to anyone skimming output, and corrosive to every decision-grade claim on the page. The fallback branch no longer reports a confidence figure; the explicit-response branch is untouched.

---

Verification on this tree

Check	Result
test_readme_snapshot_lock + test_eu_ai_act_docs_present	62 passed
Every graq command quoted in both READMEs, machine-diffed against graq --help	0 invalid
Forbidden-word scan (compliant/certified/guaranteed/end-to-end solution)	0 violations
Stale counts (76+/74/14/Azure OpenAI/graq lessons)	0 remaining
Files byte-identical to merged private/master	✅ all 4

On the private PR the same change also passed: 931 compliance/packaging/backend tests, 145 backend tests after the mock change, ruff clean, wheel build with correct METADATA, and both fresh-install smoke tests (ubuntu + windows).

---

Claims verified before any copy was written

Every broad claim was run before it was published:

• Documents/policies ingestion is real. graq scan docs + graq learn doc on a real .docx + .md → 2 files → 41 nodes (2 DOCUMENT + 39 SECTION) with SECTION_OF edges, auto-linked to code. PDF/DOCX/PPTX/XLSX require pip install graqle[docs]; the README says so plainly.
• Local-first is true by default. sentence-transformers is not a core dependency — a default install falls back to a zero-dependency hash embedder and makes no network call. Unauthenticated graq scan repo performs no cloud sync.
• Cross-file reasoning is real. A cold-start two-file project produces IMPORTS / CALLS / DEFINES edges.

---

Note on PyPI timing

v0.83.0 is already tagged and was published to PyPI on 2026-07-31, so the live PyPI page still renders the old README. This copy reaches PyPI only on the next version bump — that is when the README_PYPI.md pointer change takes effect. Merging this PR fixes the GitHub page immediately; the PyPI page follows at the next release.

---

Files changed (4)

• README.md — full rewrite against the strategy review's 13-section information architecture
• README_PYPI.md — conversion-optimised, materially shorter, and now actually shipped to PyPI
• pyproject.toml — readme pointer, description, category keywords (all existing code keywords retained)
• graqle/backends/mock.py — placeholder confidence-score fix (the only code change)

🤖 Generated with Claude Code

[github-actions]

🛡️ GraQle PR Guardian

💥 Blast Radius: 4 modules affected

Module	Files Changed	Risk Level	Impact Radius
README.md	1	🟡 T2	1
README_PYPI.md	1	🟡 T2	1
graqle	1	🟡 T2	1
pyproject.toml	1	🟡 T2	1

Total blast radius: 4

---

🏛️ Governance Verdict

⚠️ WARN

• T2: Advisory warnings detected. Review recommended.

---

🔍 SHACL Violations

No SHACL violations detected. ✅

---

🔐 Approval Requirements

This PR requires approval from: T2

• A Senior Engineer or above must approve.

❌ Approval requirement NOT yet satisfied.

---

Metric	Value
Blast Radius	4
Files Analyzed	4
Blocked	0
SHACL Violations	0
Verdict	WARN

---

_{🔬 Powered by GraQle PR Guardian v0.1.0 · Scan completed 2026-09-14T12:58:13.330161+00:00}