@cloudgrid-io/mcp 0.15.0 → 0.16.1

package/src/corpus/templates/semantic-search/services/refresh/src/app/embeddings.py

@@ -0,0 +1,44 @@
+"""Single config point for embeddings (OpenAI-compatible).
+
+Isolated behind one module so the provider can be swapped by env var
+(EMBEDDINGS_BASE_URL / EMBEDDINGS_MODEL / EMBEDDINGS_API_KEY). NEVER reads the
+API key at import time — only inside embed(). If the key is missing, embed()
+raises EmbeddingsUnavailable, which callers translate into a graceful degraded
+state (lexical + metadata search still work).
+"""
+from __future__ import annotations
+
+import httpx
+
+from . import config
+
+
+class EmbeddingsUnavailable(RuntimeError):
+    """Raised when embeddings are requested but not configured/reachable."""
+
+
+def embed(texts: list[str]) -> list[list[float]]:
+    """Return one embedding vector per input text.
+
+    Raises EmbeddingsUnavailable if EMBEDDINGS_API_KEY is not set.
+    """
+    if not texts:
+        return []
+    key = config.embeddings_api_key()
+    if not key:
+        raise EmbeddingsUnavailable(
+            "EMBEDDINGS_API_KEY is not set — semantic embedding is unavailable."
+        )
+    resp = httpx.post(
+        f"{config.embeddings_base_url()}/embeddings",
+        headers={"Authorization": f"Bearer {key}"},
+        json={"model": config.embeddings_model(), "input": texts},
+        timeout=60.0,
+    )
+    resp.raise_for_status()
+    data = resp.json()["data"]
+    return [row["embedding"] for row in data]
+
+
+def embed_one(text: str) -> list[float]:
+    return embed([text])[0]

package/src/corpus/templates/semantic-search/services/refresh/src/app/indexing.py

@@ -0,0 +1,223 @@
+"""Incremental indexing pipeline: discover -> extract -> chunk -> embed -> store.
+
+Shared by the manager 'Refresh now' endpoint AND the scheduled `type: cron`
+refresh service (services/refresh, which vendors this module). It is resilient:
+if the source or
+embeddings are not configured it records a clear, non-crashing report and
+returns. Only new/changed files (by rev / content-hash) are reprocessed.
+"""
+from __future__ import annotations
+
+import datetime as dt
+import os
+import re
+
+from . import config, db, embeddings, source
+
+CHUNK_CHARS = 1200
+CHUNK_OVERLAP = 150
+
+# Generic date detection from filename or document head (best effort, nullable).
+_DATE_RE = re.compile(r"(\d{4})[./-](\d{1,2})[./-](\d{1,2})")        # 2026-07-05
+_DATE_RE_ALT = re.compile(r"(\d{1,2})[./-](\d{1,2})[./-](\d{2,4})")  # 05/07/2026
+
+
+def _utcnow() -> dt.datetime:
+    return dt.datetime.now(dt.timezone.utc)
+
+
+def _chunk_text(text: str) -> list[str]:
+    text = text.strip()
+    if not text:
+        return []
+    out: list[str] = []
+    start = 0
+    n = len(text)
+    while start < n:
+        end = min(start + CHUNK_CHARS, n)
+        out.append(text[start:end])
+        if end == n:
+            break
+        start = end - CHUNK_OVERLAP
+    return out
+
+
+def _parse_metadata(name: str, text: str) -> dict:
+    """Best-effort title / date / collection extraction. All fields nullable.
+
+    Generalize this for your domain: `collection` is a free-form grouping tag
+    (folder, series, category), `date` is an ISO date if one can be found.
+    """
+    title = os.path.splitext(name)[0].strip()
+    # Collection tag = the leading non-numeric words of the title.
+    collection = re.sub(r"[\d].*$", "", title).strip() or None
+
+    date_iso = None
+    haystack = f"{name}\n{text[:2000]}"
+    m = _DATE_RE.search(haystack)
+    if m:
+        y, mo, d = m.groups()
+        try:
+            date_iso = dt.datetime(int(y), int(mo), int(d)).date().isoformat()
+        except ValueError:
+            date_iso = None
+    if date_iso is None:
+        m = _DATE_RE_ALT.search(haystack)
+        if m:
+            d, mo, y = m.groups()
+            if len(y) == 2:
+                y = "20" + y
+            try:
+                date_iso = dt.datetime(int(y), int(mo), int(d)).date().isoformat()
+            except ValueError:
+                date_iso = None
+
+    return {"title": title, "collection": collection, "date": date_iso}
+
+
+def run_sync(triggered_by: str = "manual") -> dict:
+    """Run one incremental sync. Never raises on missing config — returns a report."""
+    started = _utcnow()
+    report: dict = {
+        "started_at": started,
+        "triggered_by": triggered_by,
+        "files": [],
+        "status": "ok",
+        "note": None,
+    }
+
+    # Mongo is required for indexing (and always injected). Fail loud only here.
+    db.ensure_indexes()
+
+    if not config.source_configured():
+        report["status"] = "skipped"
+        report["note"] = (
+            f"Source not configured (SOURCE_TYPE={config.source_type()!r} — "
+            "missing its secrets/config)."
+        )
+        _save_report(report)
+        return report
+
+    try:
+        src = source.get_source()
+        files = src.list_files()
+    except Exception as exc:  # noqa: BLE001 - resilient by design
+        report["status"] = "error"
+        report["note"] = f"Source listing failed: {exc}"
+        _save_report(report)
+        return report
+
+    embeddings_ok = config.embeddings_configured()
+    if not embeddings_ok:
+        report["note"] = (
+            "Embeddings not configured — documents indexed for lexical/metadata "
+            "search only (no semantic vectors)."
+        )
+
+    for f in files:
+        outcome = _process_file(src, f, embeddings_ok)
+        report["files"].append(outcome)
+
+    report["finished_at"] = _utcnow()
+    _save_report(report)
+    return report
+
+
+def _process_file(src: source.Source, f: source.SourceFile, embeddings_ok: bool) -> dict:
+    existing = db.documents().find_one({"source_filename": f.name})
+    if existing and existing.get("source_rev") == f.rev:
+        return {"file": f.name, "result": "unchanged"}
+
+    if f.is_audio and not f.is_text:
+        # Catalogue audio/media with a flag; do not search inside it.
+        doc = {
+            "title": os.path.splitext(f.name)[0],
+            "source_filename": f.name,
+            "source_rev": f.rev,
+            "file_path": f.path,
+            "collection": None,
+            "date": None,
+            "has_media": True,
+            "media_path": f.path,
+            "word_count": 0,
+            "indexed_at": _utcnow(),
+        }
+        doc_id = _upsert_document(doc)
+        db.chunks().delete_many({"document_id": doc_id})
+        return {"file": f.name, "result": "catalogued_media"}
+
+    if not f.is_text:
+        return {"file": f.name, "result": "skipped_unsupported"}
+
+    try:
+        raw = src.download(f.path)
+        text = source.extract_text(f.name, raw)
+    except Exception as exc:  # noqa: BLE001
+        return {"file": f.name, "result": "error", "detail": str(exc)}
+
+    meta = _parse_metadata(f.name, text)
+    doc = {
+        **meta,
+        "source_filename": f.name,
+        "source_rev": f.rev,
+        "file_path": f.path,
+        "has_media": False,
+        "media_path": None,
+        "word_count": len(text.split()),
+        "indexed_at": _utcnow(),
+    }
+    doc_id = _upsert_document(doc)
+
+    # Rebuild chunks for this document.
+    db.chunks().delete_many({"document_id": doc_id})
+    parts = _chunk_text(text)
+    vectors: list[list[float] | None] = [None] * len(parts)
+    if embeddings_ok and parts:
+        try:
+            vectors = embeddings.embed(parts)  # type: ignore[assignment]
+        except Exception as exc:  # noqa: BLE001
+            return {
+                "file": f.name,
+                "result": "indexed_no_embeddings",
+                "detail": f"embedding failed: {exc}",
+                "chunks": len(parts),
+            }
+
+    docs = []
+    for i, content in enumerate(parts):
+        docs.append({
+            "document_id": doc_id,
+            "chunk_index": i,
+            "content": content,
+            "embedding": vectors[i] if i < len(vectors) else None,
+            "token_count": len(content.split()),
+        })
+    if docs:
+        db.chunks().insert_many(docs)
+
+    return {
+        "file": f.name,
+        "result": "indexed" if embeddings_ok else "indexed_no_embeddings",
+        "chunks": len(docs),
+    }
+
+
+def _upsert_document(doc: dict):
+    db.documents().update_one(
+        {"source_filename": doc["source_filename"]},
+        {"$set": doc},
+        upsert=True,
+    )
+    return db.documents().find_one({"source_filename": doc["source_filename"]})["_id"]
+
+
+def _save_report(report: dict) -> None:
+    try:
+        db.index_reports().insert_one(dict(report))
+        db.settings().update_one(
+            {"_id": "catalog"},
+            {"$set": {"last_refresh": report.get("finished_at") or report["started_at"]}},
+            upsert=True,
+        )
+    except Exception:  # noqa: BLE001 - reporting must never crash the caller
+        pass

package/src/corpus/templates/semantic-search/services/refresh/src/app/source.py

@@ -0,0 +1,259 @@
+"""Pluggable document-source adapter, selected by SOURCE_TYPE.
+
+The source is where the raw documents *live*, not the query database. Three
+adapters ship here:
+
+  - dropbox : read-only Dropbox via the offline refresh-token flow.
+  - local   : a directory on the container filesystem (e.g. a `needs: disk`
+              mount at DISK_PATH, or a bundled folder via LOCAL_SOURCE_PATH).
+  - url     : a manifest of document URLs (URL_SOURCE_MANIFEST) fetched over HTTP.
+
+Add your own by subclassing Source and returning it from get_source(). Never read
+source secrets at import time; a missing config surfaces as SourceUnavailable,
+handled gracefully by the indexing pipeline (it records a report and exits 0).
+"""
+from __future__ import annotations
+
+import io
+import os
+from dataclasses import dataclass
+
+import httpx
+
+from . import config
+
+
+class SourceUnavailable(RuntimeError):
+    """Raised when the configured source is not usable (missing secrets, etc)."""
+
+
+# File classes we handle.
+TEXT_EXTS = {".txt", ".md"}
+PDF_EXTS = {".pdf"}
+DOCX_EXTS = {".docx", ".doc"}
+AUDIO_EXTS = {".mp3", ".m4a", ".wav", ".aac", ".ogg"}
+
+
+@dataclass
+class SourceFile:
+    path: str            # source-internal path/URL (never exposed to clients)
+    name: str            # filename only
+    rev: str             # content revision / hash for incremental sync
+    size: int
+    is_audio: bool
+    is_text: bool        # text-extractable (txt/md/pdf/docx)
+
+
+def _classify(name: str) -> tuple[bool, bool]:
+    ext = os.path.splitext(name)[1].lower()
+    return (ext in AUDIO_EXTS, ext in (TEXT_EXTS | PDF_EXTS | DOCX_EXTS))
+
+
+class Source:
+    def list_files(self) -> list[SourceFile]:
+        raise NotImplementedError
+
+    def download(self, path: str) -> bytes:
+        raise NotImplementedError
+
+
+# ── Dropbox adapter ───────────────────────────────────────────────────────────
+
+class DropboxSource(Source):
+    """Read-only Dropbox via the offline refresh-token flow."""
+
+    def __init__(self) -> None:
+        c = config.dropbox_config()
+        if not (c["app_key"] and c["app_secret"] and c["refresh_token"]):
+            raise SourceUnavailable(
+                "Dropbox is not configured — set DROPBOX_APP_KEY, "
+                "DROPBOX_APP_SECRET and DROPBOX_REFRESH_TOKEN."
+            )
+        self._app_key = c["app_key"]
+        self._app_secret = c["app_secret"]
+        self._refresh_token = c["refresh_token"]
+        self._folder = (c["folder_path"] or "").rstrip("/")
+        self._token: str | None = None
+
+    def _access_token(self) -> str:
+        if self._token:
+            return self._token
+        resp = httpx.post(
+            "https://api.dropbox.com/oauth2/token",
+            data={
+                "grant_type": "refresh_token",
+                "refresh_token": self._refresh_token,
+            },
+            auth=(self._app_key, self._app_secret),
+            timeout=30.0,
+        )
+        resp.raise_for_status()
+        self._token = resp.json()["access_token"]
+        return self._token
+
+    def _headers(self) -> dict[str, str]:
+        return {"Authorization": f"Bearer {self._access_token()}"}
+
+    def list_files(self) -> list[SourceFile]:
+        out: list[SourceFile] = []
+        url = "https://api.dropboxapi.com/2/files/list_folder"
+        body: dict = {"path": self._folder, "recursive": True}
+        while True:
+            resp = httpx.post(url, headers=self._headers(), json=body, timeout=60.0)
+            resp.raise_for_status()
+            payload = resp.json()
+            for entry in payload.get("entries", []):
+                if entry.get(".tag") != "file":
+                    continue
+                out.append(self._to_source_file(entry))
+            if payload.get("has_more"):
+                url = "https://api.dropboxapi.com/2/files/list_folder/continue"
+                body = {"cursor": payload["cursor"]}
+            else:
+                break
+        return out
+
+    @staticmethod
+    def _to_source_file(entry: dict) -> SourceFile:
+        name = entry["name"]
+        is_audio, is_text = _classify(name)
+        return SourceFile(
+            path=entry["path_lower"],
+            name=name,
+            rev=entry.get("content_hash") or entry.get("rev", ""),
+            size=int(entry.get("size", 0)),
+            is_audio=is_audio,
+            is_text=is_text,
+        )
+
+    def download(self, path: str) -> bytes:
+        import json
+
+        resp = httpx.post(
+            "https://content.dropboxapi.com/2/files/download",
+            headers={
+                **self._headers(),
+                "Dropbox-API-Arg": json.dumps({"path": path}),
+            },
+            timeout=120.0,
+        )
+        resp.raise_for_status()
+        return resp.content
+
+
+# ── Local-filesystem adapter ──────────────────────────────────────────────────
+
+class LocalSource(Source):
+    """Read documents from a directory on the container filesystem.
+
+    Point LOCAL_SOURCE_PATH (or a `needs: disk` mount at DISK_PATH) at a folder
+    of .txt/.md/.pdf/.docx files. `rev` is the file mtime+size, so changed files
+    re-index on the next sync.
+    """
+
+    def __init__(self) -> None:
+        root = config.local_source_path()
+        if not root:
+            raise SourceUnavailable(
+                "Local source is not configured — set LOCAL_SOURCE_PATH "
+                "(or mount a disk and it will default to DISK_PATH)."
+            )
+        if not os.path.isdir(root):
+            raise SourceUnavailable(f"LOCAL_SOURCE_PATH does not exist: {root!r}")
+        self._root = root
+
+    def list_files(self) -> list[SourceFile]:
+        out: list[SourceFile] = []
+        for dirpath, _dirs, files in os.walk(self._root):
+            for name in files:
+                full = os.path.join(dirpath, name)
+                is_audio, is_text = _classify(name)
+                try:
+                    st = os.stat(full)
+                except OSError:
+                    continue
+                out.append(SourceFile(
+                    path=full,
+                    name=name,
+                    rev=f"{int(st.st_mtime)}-{st.st_size}",
+                    size=st.st_size,
+                    is_audio=is_audio,
+                    is_text=is_text,
+                ))
+        return out
+
+    def download(self, path: str) -> bytes:
+        with open(path, "rb") as fh:
+            return fh.read()
+
+
+# ── URL-manifest adapter ──────────────────────────────────────────────────────
+
+class UrlSource(Source):
+    """Fetch documents from a manifest of URLs.
+
+    URL_SOURCE_MANIFEST is a newline- or comma-separated list of document URLs.
+    The filename is the URL's last path segment; `rev` is the URL itself
+    (override by pointing the manifest at content-hashed URLs).
+    """
+
+    def __init__(self) -> None:
+        manifest = config.url_source_manifest()
+        if not manifest:
+            raise SourceUnavailable(
+                "URL source is not configured — set URL_SOURCE_MANIFEST to a "
+                "newline- or comma-separated list of document URLs."
+            )
+        raw = manifest.replace(",", "\n").splitlines()
+        self._urls = [u.strip() for u in raw if u.strip()]
+
+    def list_files(self) -> list[SourceFile]:
+        out: list[SourceFile] = []
+        for u in self._urls:
+            name = u.rstrip("/").rsplit("/", 1)[-1] or "document"
+            is_audio, is_text = _classify(name)
+            out.append(SourceFile(
+                path=u,
+                name=name,
+                rev=u,
+                size=0,
+                is_audio=is_audio,
+                is_text=is_text,
+            ))
+        return out
+
+    def download(self, path: str) -> bytes:
+        resp = httpx.get(path, timeout=120.0, follow_redirects=True)
+        resp.raise_for_status()
+        return resp.content
+
+
+def get_source() -> Source:
+    """Build the configured source adapter. Raises SourceUnavailable if unusable."""
+    st = config.source_type()
+    if st == "dropbox":
+        return DropboxSource()
+    if st == "local":
+        return LocalSource()
+    if st == "url":
+        return UrlSource()
+    raise SourceUnavailable(f"Unknown SOURCE_TYPE: {st!r}")
+
+
+# ── Text extraction (used by the pipeline) ───────────────────────────────────
+
+def extract_text(name: str, raw: bytes) -> str:
+    ext = os.path.splitext(name)[1].lower()
+    if ext in TEXT_EXTS:
+        return raw.decode("utf-8", errors="replace")
+    if ext in PDF_EXTS:
+        from pypdf import PdfReader
+
+        reader = PdfReader(io.BytesIO(raw))
+        return "\n".join((page.extract_text() or "") for page in reader.pages)
+    if ext in DOCX_EXTS:
+        from docx import Document
+
+        doc = Document(io.BytesIO(raw))
+        return "\n".join(p.text for p in doc.paragraphs)
+    return ""

package/src/corpus/templates/semantic-search/services/refresh/src/main.py

@@ -0,0 +1,45 @@
+"""CloudGrid cron-job entry point (services/refresh/src/main.py).
+
+A `type: cron` service with `run: job` runs this file to completion once per
+schedule, then exits — there is NO HTTP server here. It reuses the SAME
+incremental indexing pipeline as the manager 'Refresh now' endpoint
+(`app.indexing.run_sync`) and connects DIRECTLY to the grid-injected
+`DATABASE_MONGODB_URL` (from the app-level `needs: { database: true }`), so it
+does not depend on the backend service being reachable over the network.
+
+The backend's `app/` package is VENDORED into this service's own
+`services/refresh/src/app/` (config, db, source, embeddings, indexing). Each
+CloudGrid service builds from its own folder in an isolated container, so a
+cross-folder import of `services/backend/src/app` would not resolve here — the
+copy is the CloudGrid-native way to share the logic. See services/refresh/README.md
+for the drift note (keep the copies in sync with the backend originals).
+
+Graceful by design: if the document source or the embeddings key is not
+configured, `run_sync` records a clear report and returns WITHOUT raising, so the
+scheduled run is a clean no-op (source_configured: false / 0 documents) rather
+than a crash. No secret is read at import time.
+"""
+from __future__ import annotations
+
+import sys
+
+from app import indexing
+
+
+def main() -> int:
+    report = indexing.run_sync(triggered_by="cron")
+    status = report.get("status", "unknown")
+    note = report.get("note")
+    files = report.get("files", [])
+    # A single, greppable summary line for `grid logs` / the manager index-report.
+    print(
+        f"cron refresh: status={status} files={len(files)}"
+        + (f" note={note!r}" if note else "")
+    )
+    # A skipped/degraded run is a SUCCESS (graceful no-op), not a failure — only a
+    # genuine pipeline error should surface a non-zero exit for the scheduler.
+    return 1 if status == "error" else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/src/corpus/workflows/semantic-search.md

@@ -4,8 +4,8 @@ when: "search over my documents / PDFs / notes / knowledge base, semantic search
 needs: database
 deploy: runtime
 editions: local
-capabilities_note: "Document search — needs a database (Mongo) for the documents + chunks collections. Two services: a React (Vite) static frontend at / and a FastAPI backend at /backend. Hybrid search = Mongo $text (lexical) + in-app NumPy cosine over chunk embedding arrays (semantic) + metadata filters, blended to the document level. Runtime app, async build, local edition only. Declare needs:{database:true}. NO needs:vector — pgvector runtime role-grant is blocked (#1545), so embeddings live in the Mongo chunks collection and are cosine-ranked in-app. NO active cron — a Python type:cron refresh is blocked (#1585); ship the manager 'Refresh now' endpoint. Health is green with no secrets; startup ensure_indexes() so $text never 500s on an empty catalog. Pluggable source (dropbox|local|url) + embeddings (OpenAI-compatible) each behind one config point, all secrets from env."
-summary: "Build a document-search app on the grid — index a folder of PDFs/DOCX/TXT/MD, then search by keyword + meaning + metadata, with a grounded answer mode and manager admin. React static frontend at / + FastAPI backend at /backend, backed by grid-shared Mongo. Edition-gate first, scaffold, put the code under services/web/ + services/backend/, declare needs:{database:true} (NO vector #1545, NO active cron #1585), set the embeddings + source + manager secrets, deploy async, poll to a live URL, then Refresh now to index."
+capabilities_note: "Document search — needs a database (Mongo) for the documents + chunks collections. Two services: a React (Vite) static frontend at / and a FastAPI backend at /backend. Hybrid search = Mongo $text (lexical) + in-app NumPy cosine over chunk embedding arrays (semantic) + metadata filters, blended to the document level. Runtime app, async build, local edition only. Declare needs:{database:true}. NO needs:vector — pgvector runtime role-grant is blocked (#1545), so embeddings live in the Mongo chunks collection and are cosine-ranked in-app. Two refresh paths: the manager 'Refresh now' endpoint AND a scheduled Python type:cron job (services/refresh, daily 03:00 UTC) that vendors the backend app/ modules and reuses indexing.run_sync — both degrade gracefully. Health is green with no secrets; startup ensure_indexes() so $text never 500s on an empty catalog. Pluggable source (dropbox|local|url) + embeddings (OpenAI-compatible) each behind one config point, all secrets from env."
+summary: "Build a document-search app on the grid — index a folder of PDFs/DOCX/TXT/MD, then search by keyword + meaning + metadata, with a grounded answer mode and manager admin. React static frontend at / + FastAPI backend at /backend, backed by grid-shared Mongo. Edition-gate first, scaffold, put the code under services/web/ + services/backend/, declare needs:{database:true} (NO vector #1545), wire the web+backend+refresh services, set the embeddings + source + manager secrets, deploy async, poll to a live URL, then Refresh now (or wait for the daily cron) to index."
 recipe: "edition-gate -> auth+grid -> gridctl_init -> fetch template + read AGENTS.md -> put code under services/web + services/backend, set cloudgrid.yaml active fields -> grid secrets set (embeddings + source + MANAGER_PASSWORD_HASH) -> optional grid dev -> grid plug (async, poll) -> Refresh now to index -> return live URL"
 ---
 
@@ -53,7 +53,7 @@ writing anything — it defines the file tree, the `documents` + `chunks`
 collections + fields, the Mongo injection, the pluggable source adapter, the
 embeddings config point, the secrets, the deploy flow, and the four baked-in
 learnings you must NOT regress (health-without-secrets, startup index, `$text`
-guard, no vector / no cron).
+guard, no `needs: vector`).
 
 ## 5. Put the code under services/ and fill cloudgrid.yaml
 
@@ -74,6 +74,11 @@ services:
   backend:
     type: python
     path: /backend
+  refresh:                 # scheduled reindex — Python cron, batch job
+    type: cron
+    schedule: "0 3 * * *"  # daily 03:00
+    timezone: UTC
+    run: job
 needs:
   database: true
 ```
@@ -85,9 +90,12 @@ injects `DATABASE_MONGODB_URL` (+ legacy `MONGODB_URL`), read lazily in
 
 **NO `needs: vector`** — the pgvector runtime role-grant is blocked on platform
 issue **#1545**, so this template stores embeddings in the Mongo `chunks`
-collection (a float array) and cosine-ranks in-app. **NO active cron** — a Python
-`type: cron` refresh is blocked on **#1585**; the cron service stays commented and
-the manager "Refresh now" endpoint does the indexing.
+collection (a float array) and cosine-ranks in-app. **The refresh cron IS active**
+— a Python `type: cron`, `run: job` service (`services/refresh/`) reindexes daily
+at 03:00 UTC, and the manager "Refresh now" endpoint indexes on demand. Both call
+the same `indexing.run_sync`. Because each service builds in an isolated container,
+the cron **vendors** the backend `app/` modules it needs into
+`services/refresh/src/app/` (keep the copies in sync — see AGENTS.md §8).
 
 ## 6. Configure the source + embeddings (one config point each)
 
@@ -124,10 +132,11 @@ response is `status: "building"`, NOT a live URL yet.
 ## 9. Index + iterate
 
 Sign in as manager and hit **"Refresh now"** (Settings) to index the source into
-Mongo, then search. Give the user the live app URL — the deliverable. To iterate,
-re-plug the SAME entity so it updates the same URL.
+Mongo immediately, then search — or let the daily `refresh` cron do it on schedule.
+Give the user the live app URL — the deliverable. To iterate, re-plug the SAME
+entity so it updates the same URL.
 
 Keep it honest: this ships real code you adapt, the build is async and
 local-edition only, Mongo is injected by `needs`, embeddings live in Mongo (no
-pgvector until #1545), and refresh is a manual endpoint until the cron unblocks
-(#1585).
+pgvector until #1545), and refresh runs both on demand (endpoint) and on a schedule
+(the `refresh` cron).