This layer adds semantic search capability to the atlas across its published pages. Its function is not to give a final answer about Shahrur, but to open a path to the places closest to the reader’s question: a concept, a citation, a reading path, or a source.
How does it work?
The atlas pages are divided into short segments: sources, claim atoms, aggregations, conceptual relations, lexicon, concept centers, and reading paths. These segments are then converted into numerical representations stored in a vector database on Cloudflare.
When a reader writes a question, the question is converted in the same way, and then the closest segments are retrieved. In search, the segments and their links appear. In question-and-answer mode, the model is not asked to answer from its general memory, but only from the retrieved segments.
What does it add to the atlas?
- It helps a reader who does not know the exact term reach the nearest entry point.
- It reveals the possible paths between an ordinary question and the organized pages within the atlas.
- It connects the question to examinable loci rather than settling for a general summary.
- It shows editorial gaps when search cannot find sufficient support for an important question.
It also adds a more directive use through the question-based reading-path generator: it does not give a final answer, but proposes the reading sequence itself: a starting concept, a published path, evidence, and then a point of tension.
It also adds the Qur’anic mirror for the Shahrur atlas as a special interface for questions close to Qur’anic loci: it displays verses that are used, nearby, or at a point of tension within the atlas, as evidence for examination rather than automatic interpretation or a final judgment.
What are its limits?
Semantic search measures the proximity between the question and the segments, not the truth of the idea. It may therefore retrieve a segment that is linguistically close but not sufficient for judgment. The quality of the result also depends on the quality of the source texts, the segmentation, and the completeness of the atlas pages.
For this reason, the result remains a reading entry point, not a substitute for reading. If the retrieved segments are not enough, that should be made clear rather than building an answer from outside the material.
What does this page not store?
This page does not store API keys or secret values. Secrets are managed outside the published content and are mentioned here only in terms of their function: connecting the atlas to the vector database, running embedding models, and protecting the segment-ingestion pipeline.
When does the index speak?
During the active build phase, the semantic index updates after every publication that changes material published in the atlas: a reading path, concept center, lexicon, claim atom, aggregation, source, or verse page. In this way, what the reader searches remains close to the version published on the site.
The index does not need updating for a purely visual edit, a change in a page not included in the published material, or a technical task that does not alter the texts the reader searches.
Once the atlas structure stabilizes and most changes become linguistic or minor, updates may move from every publication to a lighter rhythm: weekly, before launching a major path, or after any change that alters the reader’s expected answer.
Editorial rule
Every use of this layer must lead to a page, a citation, or a path within the atlas. If the answer begins to replace the source, the layer has departed from its function. But if it opens a door to examination, comparison, and objection, it is operating as part of the atlas’s structure.
This applies especially to the Qur’anic mirror: the value of the result lies in telling the reader where to examine the verse or its use within Shahrur’s project, not what the meaning of the verse must be.