[ChinaYiqun]

What changed

• adds a complete no-API-key RAG demo that runs without a model download, database, framework, or credentials;
• adds deterministic local hashing embeddings and an explicitly labeled extractive generator for the demo path;
• adds offline tests that verify the local deployment passage is retrieved and cited;
• runs the no-key demo in GitHub Actions on every PR;
• redesigns the English and Chinese README first screens around a clear product position, one-command quickstart, expected output, architecture diagram, maturity table, framework differentiation, roadmap, and contribution call-to-action;
• adds an architecture guide with extension points and honest maturity levels;
• adds a contributor guide, bug/feature issue forms, and a pull request template.

Why

The repository already contains useful Java RAG components, but the first-run experience required credentials and the README led with setup details rather than a clear reason to care. That hurts GitHub search conversion: visitors cannot quickly prove the project works or understand why they should choose it over a larger Java AI framework.

This PR creates a shareable entry point:

bash scripts/run-no-api-demo.sh

It demonstrates the complete path:

chunk -> embed -> retrieve -> Top-K context -> grounded prompt -> cited answer

Positioning

Java-RAG is positioned as a transparent, framework-free, Java 8-compatible RAG learning and integration toolkit. It does not claim to replace LangChain4j or Spring AI; it serves developers who want to understand the pipeline, embed it into an existing Java system, or replace individual stages directly.

Validation

GitHub Actions runs:

bash scripts/check-no-hardcoded-secrets.sh
mvn --batch-mode --no-transfer-progress test
bash scripts/run-no-api-demo.sh

The demo is intentionally deterministic and offline. Its hashing embeddings and extractive generator are learning/test components, not production model substitutes.