Skip to content

armgit / xerj

Public Imported from GitHub
0

AI search engine and MCP server for bots and agents. One Rust binary indexes code, docs, logs, JSONL/CSV and PDFs for BM25 full-text, vector and hybrid search, code search without grep, agent memory and RAG. Elasticsearch-compatible API; Corpus Hub serves hundreds of reference memory corpora.

fix(seo): require updated: frontmatter in every article source (#974)

xerj-org30d47148e8a8
diff --git a/.github/workflows/seo.yml b/.github/workflows/seo.yml
index c2bd77420..c4a017c50 100644
--- a/.github/workflows/seo.yml
+++ b/.github/workflows/seo.yml
@@ -55,6 +55,13 @@ jobs:
with:
python-version: '3.12'
+ # #974: `updated:` is required frontmatter. Before it was, an article
+ # could omit the field and silently date itself from the content file's
+ # git committer date, which a squash merge rewrites — main then went red
+ # on every check below the moment such a PR merged.
+ - name: Article frontmatter schema unit tests
+ run: python3 scripts/seo/test_article_schema.py
+
- name: generated articles are current
run: python3 scripts/seo/build_articles.py --check
diff --git a/content/answers/agent-memory-without-postgres-qdrant.md b/content/answers/agent-memory-without-postgres-qdrant.md
index 4a0a86551..c7794d0ce 100644
--- a/content/answers/agent-memory-without-postgres-qdrant.md
+++ b/content/answers/agent-memory-without-postgres-qdrant.md
@@ -7,6 +7,7 @@ cluster: "Agent memory: topology"
question: "I want persistent agent memory without standing up Postgres or Qdrant. What do people use?"
intent: "tool-selection"
published: "2026-08-21"
+updated: "2026-08-23"
author: "XERJ documentation team"
reviewer: "XERJ engineering team"
schema_type: "TechArticle"
diff --git a/content/answers/audit-php-codebase-with-an-index.md b/content/answers/audit-php-codebase-with-an-index.md
index 440d54a64..aaa03b0ea 100644
--- a/content/answers/audit-php-codebase-with-an-index.md
+++ b/content/answers/audit-php-codebase-with-an-index.md
@@ -7,6 +7,7 @@ cluster: "Code security"
question: "How do I search a large PHP repo for dangerous sinks without reading every file?"
intent: "how-to"
published: "2026-08-22"
+updated: "2026-08-23"
author: "XERJ documentation team"
reviewer: "XERJ engineering team"
schema_type: "TechArticle"
diff --git a/content/answers/autoindex-dataset-refused-by-server.md b/content/answers/autoindex-dataset-refused-by-server.md
index 449a29b17..0f794fa43 100644
--- a/content/answers/autoindex-dataset-refused-by-server.md
+++ b/content/answers/autoindex-dataset-refused-by-server.md
@@ -7,6 +7,7 @@ cluster: "Operations: exit codes"
question: "Why did xerj autoindex say a dataset was refused by the server?"
intent: "troubleshooting"
published: "2026-09-18"
+updated: "2026-09-20"
author: "XERJ documentation team"
reviewer: "XERJ engineering team"
schema_type: "TechArticle"
diff --git a/content/answers/autoindex-exit-codes.md b/content/answers/autoindex-exit-codes.md
index d45d12e2d..c374ebb68 100644
--- a/content/answers/autoindex-exit-codes.md
+++ b/content/answers/autoindex-exit-codes.md
@@ -7,6 +7,7 @@ cluster: "Operations: exit codes"
question: "What does indexer exit code 3 mean?"
intent: "troubleshooting"
published: "2026-08-22"
+updated: "2026-09-20"
author: "XERJ documentation team"
reviewer: "XERJ engineering team"
schema_type: "TechArticle"
diff --git a/content/answers/autoindex-says-extract-the-archive-first.md b/content/answers/autoindex-says-extract-the-archive-first.md
index 834e59d62..75ad8ec4a 100644
--- a/content/answers/autoindex-says-extract-the-archive-first.md
+++ b/content/answers/autoindex-says-extract-the-archive-first.md
@@ -7,6 +7,7 @@ cluster: "Operations: exit codes"
question: "Why does xerj autoindex say to extract a zip first?"
intent: "troubleshooting"
published: "2026-09-18"
+updated: "2026-09-20"
author: "XERJ documentation team"
reviewer: "XERJ engineering team"
schema_type: "TechArticle"
diff --git a/content/answers/autoindex-server-back-pressure-429.md b/content/answers/autoindex-server-back-pressure-429.md
index 1f2189b91..2714565b2 100644
--- a/content/answers/autoindex-server-back-pressure-429.md
+++ b/content/answers/autoindex-server-back-pressure-429.md
@@ -7,6 +7,7 @@ cluster: "Operations: exit codes"
question: "Why did xerj autoindex say the server pushed back with HTTP 429?"
intent: "troubleshooting"
published: "2026-09-18"
+updated: "2026-09-20"
author: "XERJ documentation team"
reviewer: "XERJ engineering team"
schema_type: "TechArticle"
diff --git a/content/answers/cheap-low-volume-log-search.md b/content/answers/cheap-low-volume-log-search.md
index 070912b41..7a071f3be 100644
--- a/content/answers/cheap-low-volume-log-search.md
+++ b/content/answers/cheap-low-volume-log-search.md
@@ -7,6 +7,7 @@ cluster: "Operations: low-volume logs"
question: "Free or cheap alternative for low volume log management and searching?"
intent: "tool-selection"
published: "2026-08-21"
+updated: "2026-08-23"
author: "XERJ documentation team"
reviewer: "XERJ engineering team"
schema_type: "TechArticle"
diff --git a/content/answers/check-codebase-index-is-complete.md b/content/answers/check-codebase-index-is-complete.md
index de70771fc..4f9b64371 100644
--- a/content/answers/check-codebase-index-is-complete.md
+++ b/content/answers/check-codebase-index-is-complete.md
@@ -7,6 +7,7 @@ cluster: "Operations: completeness"
question: "My codebase indexer says indexed but I don't see my code. How do I check it actually finished?"
intent: "troubleshooting"
published: "2026-08-21"
+updated: "2026-08-23"
author: "XERJ documentation team"
reviewer: "XERJ engineering team"
schema_type: "TechArticle"
diff --git a/content/answers/classify-text-from-labelled-history-without-llm.md b/content/answers/classify-text-from-labelled-history-without-llm.md
index 657cbbdb9..f15f9cb5c 100644
--- a/content/answers/classify-text-from-labelled-history-without-llm.md
+++ b/content/answers/classify-text-from-labelled-history-without-llm.md
@@ -7,6 +7,7 @@ cluster: "Decisions as retrieval"
question: "Can I classify text from labelled history without calling an LLM?"
intent: "informational"
published: "2026-09-18"
+updated: "2026-09-20"
author: "XERJ documentation team"
reviewer: "XERJ engineering team"
schema_type: "TechArticle"
diff --git a/content/answers/coding-agent-memory-across-sessions.md b/content/answers/coding-agent-memory-across-sessions.md
index b550ed7ae..17cb8d5a7 100644
--- a/content/answers/coding-agent-memory-across-sessions.md
+++ b/content/answers/coding-agent-memory-across-sessions.md
@@ -7,6 +7,7 @@ cluster: "Agent memory: setup"
question: "How do people store user preferences so an agent can recall them next week?"
intent: "how-to"
published: "2026-08-21"
+updated: "2026-09-13"
author: "XERJ documentation team"
reviewer: "XERJ engineering team"
schema_type: "TechArticle"
diff --git a/content/answers/do-search-embeddings-help.md b/content/answers/do-search-embeddings-help.md
index 6a7f34ad2..4488434fc 100644
--- a/content/answers/do-search-embeddings-help.md
+++ b/content/answers/do-search-embeddings-help.md
@@ -7,6 +7,7 @@ cluster: "Embeddings: selection"
question: "Do I even need embeddings for search, or is full-text enough?"
intent: "informational"
published: "2026-08-21"
+updated: "2026-08-23"
author: "XERJ documentation team"
reviewer: "XERJ engineering team"
schema_type: "TechArticle"
diff --git a/content/answers/does-xerj-support-s3-alerting-plugins.md b/content/answers/does-xerj-support-s3-alerting-plugins.md
index 7119caab9..df4f057fe 100644
--- a/content/answers/does-xerj-support-s3-alerting-plugins.md
+++ b/content/answers/does-xerj-support-s3-alerting-plugins.md
@@ -7,6 +7,7 @@ cluster: "Capabilities and limits"
question: "Can XERJ store its index in S3, send alerts, or run my own ingest plugin?"
intent: "informational"
published: "2026-09-18"
+updated: "2026-09-19"
author: "XERJ documentation team"
reviewer: "XERJ engineering team"
schema_type: "TechArticle"
diff --git a/content/answers/estimate-autoindex-time-before-running.md b/content/answers/estimate-autoindex-time-before-running.md
index 313efa380..563579b51 100644
--- a/content/answers/estimate-autoindex-time-before-running.md
+++ b/content/answers/estimate-autoindex-time-before-running.md
@@ -7,6 +7,7 @@ cluster: "Operations: estimation"
question: "How long will it take to index a folder for search?"
intent: "cost"
published: "2026-08-21"
+updated: "2026-08-23"
author: "XERJ documentation team"
reviewer: "XERJ engineering team"
schema_type: "TechArticle"
diff --git a/content/answers/evidence-for-agent-memory-links.md b/content/answers/evidence-for-agent-memory-links.md
index 2780ac9d7..f5a07947e 100644
--- a/content/answers/evidence-for-agent-memory-links.md
+++ b/content/answers/evidence-for-agent-memory-links.md
@@ -7,6 +7,7 @@ cluster: "Agent memory: provenance"
question: "Agent memory: knowledge graphs aren't enough, we need a know-how graph"
intent: "informational"
published: "2026-08-21"
+updated: "2026-08-23"
author: "XERJ documentation team"
reviewer: "XERJ engineering team"
schema_type: "TechArticle"
diff --git a/content/answers/filter-knn-exact-scan-caveat.md b/content/answers/filter-knn-exact-scan-caveat.md
index 236b58d32..dadb26172 100644
--- a/content/answers/filter-knn-exact-scan-caveat.md
+++ b/content/answers/filter-knn-exact-scan-caveat.md
@@ -7,6 +7,7 @@ cluster: "Retrieval behaviour"
question: "Why is filtered kNN slower than unfiltered?"
intent: "troubleshooting"
published: "2026-08-22"
+updated: "2026-08-23"
author: "XERJ documentation team"
reviewer: "XERJ engineering team"
schema_type: "TechArticle"
diff --git a/content/answers/how-xerj-combines-search.md b/content/answers/how-xerj-combines-search.md
index a3317e10b..ebd50cc78 100644
--- a/content/answers/how-xerj-combines-search.md
+++ b/content/answers/how-xerj-combines-search.md
@@ -7,6 +7,7 @@ cluster: "Hybrid search"
question: "How does XERJ combine BM25 and kNN?"
intent: "informational"
published: "2026-08-21"
+updated: "2026-08-23"
author: "XERJ documentation team"
reviewer: "XERJ engineering team"
schema_type: "TechArticle"
diff --git a/content/answers/hybrid-search-quality-measured-ndcg.md b/content/answers/hybrid-search-quality-measured-ndcg.md
index b64e75f0f..434d2e53e 100644
--- a/content/answers/hybrid-search-quality-measured-ndcg.md
+++ b/content/answers/hybrid-search-quality-measured-ndcg.md
@@ -7,6 +7,7 @@ cluster: "Hybrid retrieval: quality"
question: "How much better is hybrid search than BM25 alone?"
intent: "informational"
published: "2026-09-18"
+updated: "2026-09-20"
author: "XERJ documentation team"
reviewer: "XERJ engineering team"
schema_type: "TechArticle"
diff --git a/content/answers/improve-basic-faiss-rag-pipeline.md b/content/answers/improve-basic-faiss-rag-pipeline.md
index 62239c4b3..d54fb702f 100644
--- a/content/answers/improve-basic-faiss-rag-pipeline.md
+++ b/content/answers/improve-basic-faiss-rag-pipeline.md
@@ -7,6 +7,7 @@ cluster: "RAG: troubleshooting"
question: "How can I improve a basic FAISS RAG pipeline?"
intent: "troubleshooting"
published: "2026-08-21"
+updated: "2026-08-23"
author: "XERJ documentation team"
reviewer: "XERJ engineering team"
schema_type: "TechArticle"
diff --git a/content/answers/index-reference-library-for-coding-agent.md b/content/answers/index-reference-library-for-coding-agent.md
index 26207b8c8..933870507 100644
--- a/content/answers/index-reference-library-for-coding-agent.md
+++ b/content/answers/index-reference-library-for-coding-agent.md
@@ -7,6 +7,7 @@ cluster: "Coding agents: reference retrieval"
question: "How do I set up reference coding so the agent retrieves a mechanism before writing code?"
intent: "how-to"
published: "2026-08-22"
+updated: "2026-08-23"
author: "XERJ documentation team"
reviewer: "XERJ engineering team"
schema_type: "TechArticle"
diff --git a/content/answers/keep-index-current-as-files-change.md b/content/answers/keep-index-current-as-files-change.md
index be2f17f06..eb11080bc 100644
--- a/content/answers/keep-index-current-as-files-change.md
+++ b/content/answers/keep-index-current-as-files-change.md
@@ -7,6 +7,7 @@ cluster: "Operations: freshness"
question: "How do I keep a search index up to date as files change, without re-indexing everything?"
intent: "how-to"
published: "2026-09-19"
+updated: "2026-09-20"
author: "XERJ documentation team"
reviewer: "XERJ engineering team"
schema_type: "TechArticle"
diff --git a/content/answers/keep-s3-bucket-index-current.md b/content/answers/keep-s3-bucket-index-current.md
index d5d6bf8c8..e0e7ca54f 100644
--- a/content/answers/keep-s3-bucket-index-current.md
+++ b/content/answers/keep-s3-bucket-index-current.md
@@ -7,6 +7,7 @@ cluster: "Object storage"
question: "My documents live in an S3 or R2 bucket. How do I keep a XERJ index current as objects change?"
intent: "informational"
published: "2026-09-19"
+updated: "2026-09-20"
author: "XERJ documentation team"
reviewer: "XERJ engineering team"
schema_type: "TechArticle"
diff --git a/content/answers/knowledge-graphs-for-agent-memory.md b/content/answers/knowledge-graphs-for-agent-memory.md
index b74c66fae..cf89c5b4b 100644
--- a/content/answers/knowledge-graphs-for-agent-memory.md
+++ b/content/answers/knowledge-graphs-for-agent-memory.md
@@ -7,6 +7,7 @@ cluster: "Agent memory: link retrieval"
question: "Ask HN: Anyone using knowledge graphs for LLM agent memory/context management?"
intent: "tool-selection"
published: "2026-08-21"
+updated: "2026-08-23"
author: "XERJ documentation team"
reviewer: "XERJ engineering team"
schema_type: "TechArticle"
diff --git a/content/answers/local-embeddings-without-openai-api.md b/content/answers/local-embeddings-without-openai-api.md
index 6c991ec04..55bf5cf7c 100644
--- a/content/answers/local-embeddings-without-openai-api.md
+++ b/content/answers/local-embeddings-without-openai-api.md
@@ -7,6 +7,7 @@ cluster: "Embeddings: local execution"
question: "I want local search that works offline, no cloud embeddings. What are my options?"
intent: "how-to"
published: "2026-08-21"
+updated: "2026-08-23"
author: "XERJ documentation team"
reviewer: "XERJ engineering team"
schema_type: "TechArticle"
diff --git a/content/answers/private-agent-memory-namespaces.md b/content/answers/private-agent-memory-namespaces.md
index 06c9f44c8..4b7961929 100644
--- a/content/answers/private-agent-memory-namespaces.md
+++ b/content/answers/private-agent-memory-namespaces.md
@@ -7,6 +7,7 @@ cluster: "Agent memory: security"
question: "How do I keep one agent's memory from leaking into another agent's?"
intent: "informational"
published: "2026-08-21"
+updated: "2026-08-23"
author: "XERJ documentation team"
reviewer: "XERJ engineering team"
schema_type: "TechArticle"
diff --git a/content/answers/rag-without-vector-database.md b/content/answers/rag-without-vector-database.md
index 6e94a7d5b..ac89d453e 100644
--- a/content/answers/rag-without-vector-database.md
+++ b/content/answers/rag-without-vector-database.md
@@ -7,6 +7,7 @@ cluster: "Hybrid retrieval: architecture"
question: "How do I build RAG without a vector database?"
intent: "how-to"
published: "2026-08-21"
+updated: "2026-08-23"
author: "XERJ documentation team"
reviewer: "XERJ engineering team"
schema_type: "TechArticle"
diff --git a/content/answers/read-autoindex-progress.md b/content/answers/read-autoindex-progress.md
index 334975afd..697fef648 100644
--- a/content/answers/read-autoindex-progress.md
+++ b/content/answers/read-autoindex-progress.md
@@ -7,6 +7,7 @@ cluster: "Operations: progress"
question: "How can I see whether folder indexing is still working?"
intent: "how-to"
published: "2026-08-21"
+updated: "2026-09-20"
author: "XERJ documentation team"
reviewer: "XERJ engineering team"
schema_type: "TechArticle"
diff --git a/content/answers/read-indexed-email-and-pdf-folder.md b/content/answers/read-indexed-email-and-pdf-folder.md
index b2d9db000..16e5fbfd7 100644
--- a/content/answers/read-indexed-email-and-pdf-folder.md
+++ b/content/answers/read-indexed-email-and-pdf-folder.md
@@ -7,6 +7,7 @@ cluster: "Files and formats"
question: "I indexed a folder of email and PDFs. How do I actually read what it found?"
intent: "how-to"
published: "2026-09-18"
+updated: "2026-09-20"
author: "XERJ documentation team"
reviewer: "XERJ engineering team"
schema_type: "TechArticle"
diff --git a/content/answers/rebuild-reference-corpus-index.md b/content/answers/rebuild-reference-corpus-index.md
index fae514b3e..749b43ea2 100644
--- a/content/answers/rebuild-reference-corpus-index.md
+++ b/content/answers/rebuild-reference-corpus-index.md
@@ -7,6 +7,7 @@ cluster: "Coding agents: reference retrieval"
question: "How do I rebuild a reference-coding corpus index from scratch?"
intent: "how-to"
published: "2026-09-18"
+updated: "2026-09-20"
author: "XERJ documentation team"
reviewer: "XERJ engineering team"
schema_type: "TechArticle"
diff --git a/content/answers/reciprocal-rank-fusion-when-to-use.md b/content/answers/reciprocal-rank-fusion-when-to-use.md
index 81479edca..84f8fa8bb 100644
--- a/content/answers/reciprocal-rank-fusion-when-to-use.md
+++ b/content/answers/reciprocal-rank-fusion-when-to-use.md
@@ -7,6 +7,7 @@ cluster: "Hybrid retrieval: RRF"
question: "What is reciprocal rank fusion and when should I use it?"
intent: "informational"
published: "2026-08-21"
+updated: "2026-08-23"
author: "XERJ documentation team"
reviewer: "XERJ engineering team"
schema_type: "TechArticle"
diff --git a/content/answers/reduce-embedding-api-cost.md b/content/answers/reduce-embedding-api-cost.md
index 5df9b126a..f4ce933f7 100644
--- a/content/answers/reduce-embedding-api-cost.md
+++ b/content/answers/reduce-embedding-api-cost.md
@@ -7,6 +7,7 @@ cluster: "Embeddings: cost"
question: "My embedding bill is too high"
intent: "cost"
published: "2026-08-21"
+updated: "2026-08-23"
author: "XERJ documentation team"
reviewer: "XERJ engineering team"
schema_type: "TechArticle"
diff --git a/content/answers/reindex-taking-forever.md b/content/answers/reindex-taking-forever.md
index 7300b49e8..941cc2718 100644
--- a/content/answers/reindex-taking-forever.md
+++ b/content/answers/reindex-taking-forever.md
@@ -7,6 +7,7 @@ cluster: "Operations: reindex"
question: "Reindexing my files is taking forever. What usually causes that?"
intent: "troubleshooting"
published: "2026-08-21"
+updated: "2026-08-23"
author: "XERJ documentation team"
reviewer: "XERJ engineering team"
schema_type: "TechArticle"
diff --git a/content/answers/rerank-search-results-calibrated-judge.md b/content/answers/rerank-search-results-calibrated-judge.md
index df2ae0e52..ec0e255a8 100644
--- a/content/answers/rerank-search-results-calibrated-judge.md
+++ b/content/answers/rerank-search-results-calibrated-judge.md
@@ -7,6 +7,7 @@ cluster: "Hybrid retrieval: reranking"
question: "How do I rerank search results with a calibrated relevance judge?"
intent: "informational"
published: "2026-09-18"
+updated: "2026-09-20"
author: "XERJ documentation team"
reviewer: "XERJ engineering team"
schema_type: "TechArticle"
diff --git a/content/answers/resume-interrupted-autoindex-run.md b/content/answers/resume-interrupted-autoindex-run.md
index d2057f558..1fcdf9c99 100644
--- a/content/answers/resume-interrupted-autoindex-run.md
+++ b/content/answers/resume-interrupted-autoindex-run.md
@@ -7,6 +7,7 @@ cluster: "Operations: recovery"
question: "The indexer died overnight. Do I have to start over?"
intent: "troubleshooting"
published: "2026-08-21"
+updated: "2026-08-23"
author: "XERJ documentation team"
reviewer: "XERJ engineering team"
schema_type: "TechArticle"
diff --git a/content/answers/search-engine-without-docker.md b/content/answers/search-engine-without-docker.md
index 39f6cdb53..da452c802 100644
--- a/content/answers/search-engine-without-docker.md
+++ b/content/answers/search-engine-without-docker.md
@@ -7,6 +7,7 @@ cluster: "Operations: installation"
question: "Is there a single-binary local search engine I can just run?"
intent: "cost"
published: "2026-08-21"
+updated: "2026-08-23"
author: "XERJ documentation team"
reviewer: "XERJ engineering team"
schema_type: "TechArticle"
diff --git a/content/answers/search-files-in-an-s3-bucket.md b/content/answers/search-files-in-an-s3-bucket.md
index 2e07842ba..0f5349846 100644
--- a/content/answers/search-files-in-an-s3-bucket.md
+++ b/content/answers/search-files-in-an-s3-bucket.md
@@ -7,6 +7,7 @@ cluster: "Ingest: object storage"
question: "How do I search files that live in an S3 bucket?"
intent: "informational"
published: "2026-09-19"
+updated: "2026-09-19"
author: "XERJ documentation team"
reviewer: "XERJ engineering team"
schema_type: "TechArticle"
diff --git a/content/answers/search-gmail-takeout-mbox-locally.md b/content/answers/search-gmail-takeout-mbox-locally.md
index e29b02ea5..6d92298ad 100644
--- a/content/answers/search-gmail-takeout-mbox-locally.md
+++ b/content/answers/search-gmail-takeout-mbox-locally.md
@@ -7,6 +7,7 @@ cluster: "Folder indexing"
question: "How do I search a Google Takeout mbox file locally?"
intent: "informational"
published: "2026-09-18"
+updated: "2026-09-20"
author: "XERJ documentation team"
reviewer: "XERJ engineering team"
schema_type: "TechArticle"
diff --git a/content/answers/search-gzipped-csv-or-json.md b/content/answers/search-gzipped-csv-or-json.md
index ffbac0663..3534a833f 100644
--- a/content/answers/search-gzipped-csv-or-json.md
+++ b/content/answers/search-gzipped-csv-or-json.md
@@ -7,6 +7,7 @@ cluster: "Files and formats"
question: "How do I search gzipped CSV exports?"
intent: "how-to"
published: "2026-08-22"
+updated: "2026-08-23"
author: "XERJ documentation team"
reviewer: "XERJ engineering team"
schema_type: "TechArticle"
diff --git a/content/answers/set-mcp-memory-storage-path.md b/content/answers/set-mcp-memory-storage-path.md
index 0394f5e54..0e83dc61b 100644
--- a/content/answers/set-mcp-memory-storage-path.md
+++ b/content/answers/set-mcp-memory-storage-path.md
@@ -7,6 +7,7 @@ cluster: "Agent memory: storage"
question: "Memory MCP ignores custom storage path setting"
intent: "troubleshooting"
published: "2026-08-21"
+updated: "2026-08-23"
author: "XERJ documentation team"
reviewer: "XERJ engineering team"
schema_type: "TechArticle"
diff --git a/content/answers/share-folder-read-only-search-without-uploading.md b/content/answers/share-folder-read-only-search-without-uploading.md
index 1a2911e6f..ed5b4a3ec 100644
--- a/content/answers/share-folder-read-only-search-without-uploading.md
+++ b/content/answers/share-folder-read-only-search-without-uploading.md
@@ -7,6 +7,7 @@ cluster: "Sharing: read-only guest access"
question: "I need my accountant to search a folder of emails and PDFs. How do I do that without uploading everything somewhere?"
intent: "how-to"
published: "2026-09-18"
+updated: "2026-09-20"
author: "XERJ documentation team"
reviewer: "XERJ engineering team"
schema_type: "TechArticle"
diff --git a/content/answers/share-local-search-index-through-a-tunnel.md b/content/answers/share-local-search-index-through-a-tunnel.md
index 2fc94ced7..aadcc0c2d 100644
--- a/content/answers/share-local-search-index-through-a-tunnel.md
+++ b/content/answers/share-local-search-index-through-a-tunnel.md
@@ -7,6 +7,7 @@ cluster: "Sharing: read-only guest access"
question: "How can I give a remote person temporary search access to files on my laptop without port forwarding or a VPN?"
intent: "how-to"
published: "2026-09-18"
+updated: "2026-09-20"
author: "XERJ documentation team"
reviewer: "XERJ engineering team"
schema_type: "TechArticle"
diff --git a/content/answers/store-agent-memory-without-llm-call.md b/content/answers/store-agent-memory-without-llm-call.md
index cf0cfaa28..ce14150f3 100644
--- a/content/answers/store-agent-memory-without-llm-call.md
+++ b/content/answers/store-agent-memory-without-llm-call.md
@@ -7,6 +7,7 @@ cluster: "Agent memory: model dependency"
question: "How do I dedup agent memory?"
intent: "how-to"
published: "2026-08-21"
+updated: "2026-09-13"
author: "XERJ documentation team"
reviewer: "XERJ engineering team"
schema_type: "TechArticle"
diff --git a/content/answers/vector-database-vs-full-text-search.md b/content/answers/vector-database-vs-full-text-search.md
index f1d825eef..c6c0555f5 100644
--- a/content/answers/vector-database-vs-full-text-search.md
+++ b/content/answers/vector-database-vs-full-text-search.md
@@ -7,6 +7,7 @@ cluster: "Retrieval: selection"
question: "What's the actual difference between a vector database and full-text search?"
intent: "informational"
published: "2026-08-21"
+updated: "2026-08-23"
author: "XERJ documentation team"
reviewer: "XERJ engineering team"
schema_type: "TechArticle"
diff --git a/content/answers/what-a-share-link-guest-can-reach.md b/content/answers/what-a-share-link-guest-can-reach.md
index 53bd50071..c2ce1e1ea 100644
--- a/content/answers/what-a-share-link-guest-can-reach.md
+++ b/content/answers/what-a-share-link-guest-can-reach.md
@@ -7,6 +7,7 @@ cluster: "Sharing: read-only guest access"
question: "If I give someone a read-only share link to one search index, can they see my other indices or anything else on the server?"
intent: "informational"
published: "2026-09-18"
+updated: "2026-09-20"
author: "XERJ documentation team"
reviewer: "XERJ engineering team"
schema_type: "TechArticle"
diff --git a/content/answers/what-is-xerj.md b/content/answers/what-is-xerj.md
index 9dc25d928..e4ebf760a 100644
--- a/content/answers/what-is-xerj.md
+++ b/content/answers/what-is-xerj.md
@@ -7,6 +7,7 @@ cluster: "Product identity"
question: "What is XERJ?"
intent: "informational"
published: "2026-08-21"
+updated: "2026-08-23"
author: "XERJ documentation team"
reviewer: "XERJ engineering team"
schema_type: "TechArticle"
diff --git a/content/answers/why-autoindex-skipped-files.md b/content/answers/why-autoindex-skipped-files.md
index ff002f1bc..6bd79cfc3 100644
--- a/content/answers/why-autoindex-skipped-files.md
+++ b/content/answers/why-autoindex-skipped-files.md
@@ -7,6 +7,7 @@ cluster: "Operations: exclusions"
question: "Why would a folder search miss files that I can see on disk?"
intent: "troubleshooting"
published: "2026-08-21"
+updated: "2026-08-23"
author: "XERJ documentation team"
reviewer: "XERJ engineering team"
schema_type: "TechArticle"
diff --git a/content/compare/xerj-vs-ast-grep.md b/content/compare/xerj-vs-ast-grep.md
index d05234b1d..92bdeb097 100644
--- a/content/compare/xerj-vs-ast-grep.md
+++ b/content/compare/xerj-vs-ast-grep.md
@@ -7,6 +7,7 @@ cluster: "Comparison: code retrieval"
question: "ast-grep vs a code index for an agent?"
intent: "comparison"
published: "2026-08-22"
+updated: "2026-08-23"
author: "XERJ documentation team"
reviewer: "XERJ engineering team"
schema_type: "TechArticle"
diff --git a/content/compare/xerj-vs-docfetcher.md b/content/compare/xerj-vs-docfetcher.md
index ce5cf74ed..4871dc501 100644
--- a/content/compare/xerj-vs-docfetcher.md
+++ b/content/compare/xerj-vs-docfetcher.md
@@ -7,6 +7,7 @@ cluster: "Comparison: desktop search"
question: "What is a free DocFetcher alternative that an agent can call?"
intent: "comparison"
published: "2026-08-22"
+updated: "2026-08-23"
author: "XERJ documentation team"
reviewer: "XERJ engineering team"
schema_type: "TechArticle"
diff --git a/content/compare/xerj-vs-elasticsearch-local.md b/content/compare/xerj-vs-elasticsearch-local.md
index 431f28711..bd0951d2f 100644
--- a/content/compare/xerj-vs-elasticsearch-local.md
+++ b/content/compare/xerj-vs-elasticsearch-local.md
@@ -7,6 +7,7 @@ cluster: "Comparison: local search engines"
question: "Is there an Elasticsearch-compatible engine that isn't Elasticsearch?"
intent: "comparison"
published: "2026-08-22"
+updated: "2026-08-23"
author: "XERJ documentation team"
reviewer: "XERJ engineering team"
schema_type: "TechArticle"
diff --git a/content/compare/xerj-vs-houdahspot.md b/content/compare/xerj-vs-houdahspot.md
index f36975c08..f4a063fdb 100644
--- a/content/compare/xerj-vs-houdahspot.md
+++ b/content/compare/xerj-vs-houdahspot.md
@@ -7,6 +7,7 @@ cluster: "Comparison: desktop search"
question: "HoudahSpot vs a local search engine I can script?"
intent: "comparison"
published: "2026-08-22"
+updated: "2026-08-23"
author: "XERJ documentation team"
reviewer: "XERJ engineering team"
schema_type: "TechArticle"
diff --git a/content/compare/xerj-vs-khoj.md b/content/compare/xerj-vs-khoj.md
index 3a24826f3..c661bd26e 100644
--- a/content/compare/xerj-vs-khoj.md
+++ b/content/compare/xerj-vs-khoj.md
@@ -7,6 +7,7 @@ cluster: "Comparison: personal search"
question: "What's a simpler alternative to Khoj if I only need search and memory?"
intent: "comparison"
published: "2026-08-22"
+updated: "2026-08-23"
author: "XERJ documentation team"
reviewer: "XERJ engineering team"
schema_type: "TechArticle"
diff --git a/content/compare/xerj-vs-localsynapse.md b/content/compare/xerj-vs-localsynapse.md
index 71363fb1b..f01805a8b 100644
--- a/content/compare/xerj-vs-localsynapse.md
+++ b/content/compare/xerj-vs-localsynapse.md
@@ -7,6 +7,7 @@ cluster: "Comparison: local MCP search"
question: "What's a local MCP search engine for Claude?"
intent: "comparison"
published: "2026-08-22"
+updated: "2026-08-23"
author: "XERJ documentation team"
reviewer: "XERJ engineering team"
schema_type: "TechArticle"
diff --git a/content/compare/xerj-vs-meilisearch.md b/content/compare/xerj-vs-meilisearch.md
index 5353107b2..cd408a19b 100644
--- a/content/compare/xerj-vs-meilisearch.md
+++ b/content/compare/xerj-vs-meilisearch.md
@@ -7,6 +7,7 @@ cluster: "Comparison: search engines"
question: "What's a local alternative to Meilisearch that indexes a folder by itself?"
intent: "comparison"
published: "2026-08-22"
+updated: "2026-08-23"
author: "XERJ documentation team"
reviewer: "XERJ engineering team"
schema_type: "TechArticle"
diff --git a/content/compare/xerj-vs-obsidian-omnisearch.md b/content/compare/xerj-vs-obsidian-omnisearch.md
index 74d865b32..0ffbeaae9 100644
--- a/content/compare/xerj-vs-obsidian-omnisearch.md
+++ b/content/compare/xerj-vs-obsidian-omnisearch.md
@@ -7,6 +7,7 @@ cluster: "Comparison: notes and vaults"
question: "How do I search an Obsidian vault from outside Obsidian?"
intent: "comparison"
published: "2026-08-22"
+updated: "2026-08-23"
author: "XERJ documentation team"
reviewer: "XERJ engineering team"
schema_type: "TechArticle"
diff --git a/content/compare/xerj-vs-pagefind.md b/content/compare/xerj-vs-pagefind.md
index 8b14251d4..741ae3ba2 100644
--- a/content/compare/xerj-vs-pagefind.md
+++ b/content/compare/xerj-vs-pagefind.md
@@ -7,6 +7,7 @@ cluster: "Comparison: site and export search"
question: "Pagefind vs indexing a local HTML dump for an agent?"
intent: "comparison"
published: "2026-08-22"
+updated: "2026-08-23"
author: "XERJ documentation team"
reviewer: "XERJ engineering team"
schema_type: "TechArticle"
diff --git a/content/compare/xerj-vs-recoll.md b/content/compare/xerj-vs-recoll.md
index 11761fdd4..cfa47bd9d 100644
--- a/content/compare/xerj-vs-recoll.md
+++ b/content/compare/xerj-vs-recoll.md
@@ -7,6 +7,7 @@ cluster: "Comparison: desktop search"
question: "What is the best local desktop search for a folder of PDFs and docs?"
intent: "comparison"
published: "2026-08-22"
+updated: "2026-08-23"
author: "XERJ documentation team"
reviewer: "XERJ engineering team"
schema_type: "TechArticle"
diff --git a/content/compare/xerj-vs-ripgrep-all.md b/content/compare/xerj-vs-ripgrep-all.md
index 3d78f323b..900bd9dd6 100644
--- a/content/compare/xerj-vs-ripgrep-all.md
+++ b/content/compare/xerj-vs-ripgrep-all.md
@@ -7,6 +7,7 @@ cluster: "Comparison: desktop search"
question: "How do I grep PDFs and Word docs from the command line?"
intent: "comparison"
published: "2026-08-22"
+updated: "2026-08-23"
author: "XERJ documentation team"
reviewer: "XERJ engineering team"
schema_type: "TechArticle"
diff --git a/content/compare/xerj-vs-spotlight.md b/content/compare/xerj-vs-spotlight.md
index 64b694406..6ec93db51 100644
--- a/content/compare/xerj-vs-spotlight.md
+++ b/content/compare/xerj-vs-spotlight.md
@@ -7,6 +7,7 @@ cluster: "Comparison: desktop search"
question: "Spotlight can't find text inside my project files. What else is there?"
intent: "comparison"
published: "2026-08-22"
+updated: "2026-08-23"
author: "XERJ documentation team"
reviewer: "XERJ engineering team"
schema_type: "TechArticle"
diff --git a/content/compare/xerj-vs-typesense.md b/content/compare/xerj-vs-typesense.md
index e13c02071..ae9a668fb 100644
--- a/content/compare/xerj-vs-typesense.md
+++ b/content/compare/xerj-vs-typesense.md
@@ -7,6 +7,7 @@ cluster: "Comparison: search engines"
question: "Do I need Typesense for an agent to search my docs?"
intent: "comparison"
published: "2026-08-22"
+updated: "2026-08-23"
author: "XERJ documentation team"
reviewer: "XERJ engineering team"
schema_type: "TechArticle"
diff --git a/content/compare/xerj-vs-vector-database.md b/content/compare/xerj-vs-vector-database.md
index 16265ee15..6d14d8eec 100644
--- a/content/compare/xerj-vs-vector-database.md
+++ b/content/compare/xerj-vs-vector-database.md
@@ -7,6 +7,7 @@ cluster: "Comparison: vector database"
question: "Should my agent call a search API or a vector store?"
intent: "comparison"
published: "2026-08-21"
+updated: "2026-08-23"
author: "XERJ documentation team"
reviewer: "XERJ engineering team"
schema_type: "TechArticle"
diff --git a/content/compare/xerj-vs-web-agent-search.md b/content/compare/xerj-vs-web-agent-search.md
index 2b56609ba..3ff0dc346 100644
--- a/content/compare/xerj-vs-web-agent-search.md
+++ b/content/compare/xerj-vs-web-agent-search.md
@@ -7,6 +7,7 @@ cluster: "Comparison: agent retrieval"
question: "How do I let an agent search a folder on my laptop instead of crawling the web?"
intent: "comparison"
published: "2026-08-22"
+updated: "2026-08-23"
author: "XERJ documentation team"
reviewer: "XERJ engineering team"
schema_type: "TechArticle"
diff --git a/scripts/seo/README.md b/scripts/seo/README.md
index de3c47b97..d9f21ae68 100644
--- a/scripts/seo/README.md
+++ b/scripts/seo/README.md
@@ -185,6 +185,7 @@ two spaces) or an inline `[a, b]`; nested map keys under a list item are
| `question` | string | the search question the page answers |
| `intent` | string | e.g. `informational`, `commercial` |
| `published` | string | ISO `YYYY-MM-DD` |
+| `updated` | string | ISO `YYYY-MM-DD`. Required since #974: it is the page's `dateModified` and must be bumped on every real edit of the source (a new article normally starts with the same value as `published`). Before it was required, sources without it dated themselves from the content file's git committer date, which a squash merge rewrites — main then went red on `build_articles --check` the day the PR merged |
| `author` | string | shown in the source note |
| `reviewer` | string | shown in the source note |
| `schema_type` | string | `TechArticle` or `Article` — nothing else |
@@ -195,7 +196,6 @@ two spaces) or an inline `[a, b]`; nested map keys under a list item are
| Field | Type | Rules |
|---|---|---|
-| `updated` | string | ISO date. **Omit it** unless you mean to pin the date — see trap 2 |
| `evidence` | list of `{claim, source}` | `source` is an `https://` URL, a site path starting `/`, or a repo-relative path (optionally `path/to/file.rs:120`) that **must exist on disk**. Repo sources render as provenance text with no href |
| `noindex` | bool | `true` adds `robots: noindex` **and** removes the page from `sitemap.xml` (`urlmap.is_noindex` reads it) |
| `agent_prompt` | string | one logical line, must contain `https://xerj.org/llms.txt`, must not contain a Markdown fence |
@@ -236,6 +236,7 @@ cluster: "Site maintenance"
question: "How do I add a new answer article?"
intent: "informational"
published: "2026-08-21"
+updated: "2026-08-21"
author: "XERJ documentation team"
reviewer: "XERJ engineering team"
schema_type: "TechArticle"
@@ -613,9 +614,12 @@ to it.
### 2. `dateModified` comes from git, so the first commit is never the last one
-`<lastmod>` in the sitemap and `dateModified` in article JSON-LD both come from
-`git log -1 --format=%cs -- <file>` (`urlmap.DateSource`). That is deliberate:
-it is the condition Google states for trusting the field. It also means:
+Since #974 an article's `dateModified` comes from its **required `updated:`
+frontmatter field** — author-controlled data, immune to the loop below. What
+still comes from `git log -1 --format=%cs -- <file>` (`urlmap.DateSource`) is
+the sitemap's `<lastmod>`, which dates the *generated* HTML file itself. That
+is deliberate: it is the condition Google states for trusting the field. It
+also means:
```
edit source -> build (date = today's mtime fallback) -> commit
diff --git a/scripts/seo/article_data.py b/scripts/seo/article_data.py
index f36074e63..97948e210 100644
--- a/scripts/seo/article_data.py
+++ b/scripts/seo/article_data.py
@@ -31,9 +31,16 @@ TOP_FIELDS = frozenset({
# key-by-key and its sources still have to resolve.
REQUIRED_FIELDS = frozenset({
"title", "h1", "description", "slug", "cluster", "question", "intent",
- "published", "author", "reviewer", "schema_type", "links_out",
+ "published", "updated", "author", "reviewer", "schema_type", "links_out",
"faq",
})
+# `updated` was optional until #974: an article without it fell back to the
+# content file's git committer date (build_articles.article_modified), so a
+# squash merge re-dated every page regenerated before the merge and main went
+# red on `build_articles --check`. The field is now materialized in every
+# content source (value = the git date the pages already embedded, so the
+# change was a byte-level no-op on generated output) and required, which makes
+# article dates author-controlled data.
STRING_FIELDS = frozenset({
"title", "h1", "description", "slug", "cluster", "question", "intent",
"author", "reviewer", "schema_type", "agent_prompt",
@@ -396,9 +403,14 @@ def _validate(path: pathlib.Path, values: dict[str, Any], line_map: dict[str, in
"schema_type must be TechArticle or Article")
published = _date_value(values, "published", path, line_map, True)
- updated = _date_value(values, "updated", path, line_map, False)
+ updated = _date_value(values, "updated", path, line_map, True)
values.setdefault("evidence", [])
+ # Optional list fields need a default before the LIST_FIELDS loop reads
+ # them unconditionally; without this a source without `commands:` died
+ # with a bare KeyError instead of a clean schema decision (found by
+ # test_article_schema.py's minimal fixture, #974).
+ values.setdefault("commands", [])
for key in LIST_FIELDS:
value = values[key]
if not isinstance(value, list):
diff --git a/scripts/seo/test_article_schema.py b/scripts/seo/test_article_schema.py
new file mode 100644
index 000000000..902e583eb
--- /dev/null
+++ b/scripts/seo/test_article_schema.py
@@ -0,0 +1,135 @@
+#!/usr/bin/env python3
+"""Regression tests for the required `updated:` frontmatter field (#974).
+
+Until #974 an article could omit `updated:`, and build_articles fell back to
+the content file's git committer date (`article.updated or
+context.dates.last_modified(...)`). A squash merge rewrites that date to the
+merge day, so any PR whose pages were regenerated on day N went red on
+`build_articles --check` the moment it merged on day N+1 (#942 was the live
+instance; #972 band-aided it). These tests pin the fix: the field is
+materialized in every content source and `article_data.load` rejects a source
+without it, so article dates are author-controlled data and cannot drift with
+git history.
+
+Run: python3 scripts/seo/test_article_schema.py
+"""
+
+import pathlib
+import sys
+import tempfile
+import unittest
+
+sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent))
+
+import article_data
+from article_data import FrontmatterError, load
+
+REPO_ROOT = pathlib.Path(__file__).resolve().parent.parent.parent
+
+# Minimal frontmatter that passes _validate as written; each test mutates
+# only the `updated:` line it exercises.
+FRONTMATTER = """---
+title: "Schema test article"
+h1: "H1 of the schema test article?"
+description: "A minimal article that satisfies the frontmatter schema."
+slug: "schema-test-article"
+cluster: "Test cluster"
+question: "What does the schema test article cover?"
+intent: "how-to"
+published: "2026-08-21"
+updated: "2026-09-01"
+author: "XERJ documentation team"
+reviewer: "XERJ engineering team"
+schema_type: "TechArticle"
+links_out:
+ - /answers/what-is-xerj/
+faq:
+ - q: "Question one?"
+ a: "Answer one."
+ - q: "Question two?"
+ a: "Answer two."
+ - q: "Question three?"
+ a: "Answer three."
+ - q: "Question four?"
+ a: "Answer four."
+---
+Body of the schema test article.
+"""
+
+
+def _write(tmp: pathlib.Path, text: str) -> pathlib.Path:
+ # The slug must match the filename and the parent directory selects the
+ # category, so the fixture layout mirrors content/answers/.
+ directory = tmp / "answers"
+ directory.mkdir(parents=True, exist_ok=True)
+ path = directory / "schema-test-article.md"
+ path.write_text(text, encoding="utf-8")
+ return path
+
+
+class UpdatedFieldTests(unittest.TestCase):
+ def test_missing_updated_is_rejected(self):
+ # The #974 regression: before the field became required this loaded
+ # cleanly and the generator silently dated the page from git.
+ text = FRONTMATTER.replace('updated: "2026-09-01"\n', "")
+ with tempfile.TemporaryDirectory() as tmp:
+ path = _write(pathlib.Path(tmp), text)
+ with self.assertRaises(FrontmatterError) as ctx:
+ load(path)
+ self.assertIn("missing required frontmatter field(s): updated",
+ str(ctx.exception))
+
+ def test_valid_updated_is_parsed(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ path = _write(pathlib.Path(tmp), FRONTMATTER)
+ article = load(path)
+ self.assertEqual(article.updated, "2026-09-01")
+
+ def test_malformed_updated_is_rejected(self):
+ text = FRONTMATTER.replace('updated: "2026-09-01"',
+ 'updated: "Sep 1st"')
+ with tempfile.TemporaryDirectory() as tmp:
+ path = _write(pathlib.Path(tmp), text)
+ with self.assertRaises(FrontmatterError) as ctx:
+ load(path)
+ self.assertIn("updated must be an ISO date YYYY-MM-DD",
+ str(ctx.exception))
+
+ def test_impossible_calendar_date_is_rejected(self):
+ # Matches the YYYY-MM-DD shape but is not a real date, so only the
+ # date.fromisoformat fallback catches it.
+ text = FRONTMATTER.replace('updated: "2026-09-01"',
+ 'updated: "2026-09-32"')
+ with tempfile.TemporaryDirectory() as tmp:
+ path = _write(pathlib.Path(tmp), text)
+ with self.assertRaises(FrontmatterError) as ctx:
+ load(path)
+ self.assertIn("updated is not a valid ISO date", str(ctx.exception))
+
+
+class CommittedContentTests(unittest.TestCase):
+ def test_every_committed_article_carries_updated(self):
+ """No source may regress to the git-date fallback (#974's root cause).
+
+ load() already rejects a missing field, so this doubles as a check
+ that the whole committed corpus still parses under the stricter
+ schema.
+ """
+ sources = sorted(
+ (REPO_ROOT / "content").glob("answers/*.md")
+ ) + sorted((REPO_ROOT / "content").glob("compare/*.md"))
+ self.assertGreater(len(sources), 0, "no content sources found")
+ bad: list[str] = []
+ for path in sources:
+ try:
+ article = article_data.load(path)
+ except FrontmatterError as exc:
+ bad.append(str(exc))
+ continue
+ if not article.updated:
+ bad.append(f"{path}: updated is missing")
+ self.assertEqual(bad, [])
+
+
+if __name__ == "__main__":
+ unittest.main()