feat(retrieval): a System's charter becomes an answer, not just a filter (#4251)

Step 2 of #4251. A System's `description` is a charter — several hundred words
saying what belongs in that area and what does not — and it is the answer to
"which part of this codebase does X live in". There was no semantic path to
one: `list_systems` enumerates, and `search(system_id=…)` uses a System as a
FILTER over notes. So a System could narrow a search and could never be the
answer to one, and an agent asking where a record belonged had to read every
charter or guess.

ITS OWN SEARCH, not a `content_type` over notes, for the reason note 3163
gives about milestones: the row could be shared, the search cannot. A charter
competing with the whole note corpus for one top-k is outranked by the records
filed under it — the right answer crowded out by its own contents — and "where
does this belong?" is a different question from "what prior art is there?",
which a caller asking one should not have to read past answers to.

So `system_embeddings` (0107) joins note_, rule_ and milestone_embeddings as
the fourth sibling, with `system_document`, `upsert_system_embedding`,
`semantic_search_systems`, a startup backfill and `search(content_type=
"system")`. Scoped like milestones: with a project_id, that project's Systems
if the caller can read the project (rule 78); without one, the caller's own.
Archived Systems are excluded — an archived area is one the operator has said
is no longer where things go, which is exactly the question being asked.

`system_document` is the plainest of the four shapes on purpose. A charter is
already written as the thing this search has to match, in the words someone
asking would use — so there is no trigger to synthesise as `rule_document`
must, and no second record to gather as `task_document` must. The stored
charter IS the sharp document, the way a snippet's is. `color`, `status` and
`order_index` stay out: presentation and bookkeeping, and a vector carrying
them would be answering a question nobody asks of a charter.

The search publishes `report["best_chunk"]` from the start rather than being
retrofitted, which is what #4251 asked of any fourth search. It matters more
here than anywhere: a charter runs long and a result shows its NAME, so a match
on the paragraph that actually decides where a record belongs would otherwise
be previewed by two words that cannot say.

The id that comes back is the one `system_id`, `system_ids` and
`list_system_records` already take, so the answer to "where does this belong?"
is directly usable as "show me what is there" and as "file it here".

`embed_system` sits beside `notes.embed_note` at the service for #2056's
reason — every door gets it by construction. Not called on delete: that is a
soft delete and the search joins through `System`, so the vectors are already
unreachable, and leaving them means a restore is findable again immediately.
`system_embeddings` is declared in backup's `_NOT_INCLUDED` as derived, beside
its three siblings.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01821k5B3Ysecp9fNYs92Kuy

src/scribe/services/systems.py

@@ -114,6 +114,38 @@ async def seed_standard_systems(user_id: int, project_id: int) -> list[System]:
     return out
 
 
+def embed_system(system) -> None:
+    """Refresh a System's charter vectors, fire-and-forget (#4251).
+
+    The twin of `notes.embed_note`, and here for the same reason (#2056): at
+    the service, so every door gets it by construction rather than each route
+    and tool remembering. A charter edited through one door and not another
+    would stay findable by what it used to say, and nothing would report it.
+
+    Not called on delete. `delete_system` is a SOFT delete and the search joins
+    through `System`, so a deleted System's vectors are already unreachable —
+    and leaving them means a restore is findable again immediately instead of
+    waiting for the next startup backfill.
+
+    Import is lazy so importing this module doesn't pull in the embedding
+    model; a missing event loop (unit tests, scripts) is ordinary, not an
+    error; exceptions are swallowed because a System that saved must not fail
+    on its index refresh.
+    """
+    try:
+        import asyncio
+
+        from scribe.services.embeddings import upsert_system_embedding
+
+        asyncio.create_task(
+            upsert_system_embedding(system.id, system.name, system.description)
+        )
+    except RuntimeError:
+        pass          # no running loop — a sync caller, not a failure
+    except Exception:  # noqa: BLE001 - never let indexing break a write
+        logger.exception("embedding refresh failed for system %s", system.id)
+
+
 async def create_system(
     user_id: int,
     project_id: int,
@@ -144,6 +176,7 @@ async def create_system(
         session.add(system)
         await session.commit()
         await session.refresh(system)
+        embed_system(system)
         return system
 
 
@@ -195,6 +228,7 @@ async def update_system(user_id: int, system_id: int, **fields: object) -> Syste
         system.updated_at = datetime.now(timezone.utc)
         await session.commit()
         await session.refresh(system)
+        embed_system(system)
         return system