rebrand Scirium docs (Wall-O -> Scirium) + add v1/v2 documentation package

projects/scirium/docs/02-v1-scope.md

@@ -0,0 +1,67 @@
+# Scirium v1 Scope
+
+Status: PLANNED
+Applies to: v1 (grounded cited Q&A only)
+
+## 1. What v1 Ships
+
+v1 is a read-only, grounded, cited question answering assistant. A staff member asks a question in chat. Scirium retrieves the relevant passages from that channel's scoped M365 document libraries and returns an answer with inline citations to the source documents.
+
+v1 ships exactly one capability: grounded, cited Q&A. Nothing else.
+
+| Capability | In v1? | Notes |
+|---|---|---|
+| Grounded, cited Q&A | Yes | The core and only capability. |
+| Read-only retrieval over scoped M365 libraries | Yes | SharePoint and OneDrive libraries named in the channel's scope. |
+| Autonomous actions (send, write, create, update) | No | Zero. No writes to M365, no message posting beyond the answer, no integrations. |
+| Report generation, content drafts, workflows | No | Deferred to v2 and later. |
+| Patient records or PHI | No | Permanently out of scope, every version. |
+
+## 2. The v1 Contract
+
+- Every answer cites its sources inline and in a Sources footer.
+- If the answer is not in the knowledge base, Scirium says so instead of guessing.
+- Scirium never writes to the source systems. The M365 connector holds read permission only.
+- Every question and answer is logged for audit.
+
+## 3. The 6-Step Message Flow
+
+1. Staff post a question, either by @mentioning the agent in a channel or by DMing the bot.
+2. Rocket.Chat fires an outgoing webhook to the orchestrator (channel path) or the bot listener delivers a DM event (DM path).
+3. The orchestrator authenticates the request, then resolves tenant, channel, agent, and scope from the room and webhook path.
+4. Retrieval: a pgvector semantic search over the channel's vector namespace returns candidate chunks, reranked to the top set. A below-threshold result falls back to Microsoft Graph search over the scope's libraries.
+5. The orchestrator builds a prompt from the agent persona, the retrieved context with source markers, and the citation instruction, then calls admin-ai (DeepSeek V4 Pro primary with fallback).
+6. The answer is posted back to Rocket.Chat as the agent bot, with inline citations and a Sources footer.
+
+## 4. Retrieval Details
+
+| Step | Behavior |
+|---|---|
+| Primary | pgvector cosine search filtered by tenant_id and kb_scope_id in the same query. |
+| Candidate set | Top 20 by score. |
+| Rerank | Top 5 passed to the prompt. |
+| Fallback | Below threshold or empty: Microsoft Graph /search/query over the scope's document_libraries. |
+| Isolation | tenant_id and kb_scope_id filters are mandatory, so a chunk can never leak across channels or tenants. |
+
+## 5. Error Handling
+
+| Condition | v1 behavior |
+|---|---|
+| Retrieval empty or below threshold | Reply "I could not find an answer in the knowledge base for this question", no sources, never guess. |
+| LLM timeout or error | Retry once on the fallback model, then a canned "could not reach the model" reply. |
+| Channel has no agent or no scope | Configuration error reply (or silent no-op, per tenant config). |
+| Webhook retry (duplicate) | Idempotency key deduplicates; the duplicate returns 200 and is dropped. |
+| Post failure | Retry with backoff, then mark failed and surface a tenant alert. |
+
+## 6. Explicit v1 Exclusions
+
+v1 does none of the following, and this is intentional:
+
+- No actions. v1 cannot send email, create calendar items, update records, or write to any system.
+- No writes to M365. The connector is read-only.
+- No patient records or PHI, ever.
+- No multi-domain answers. A channel answers only its own scope.
+- No proactive messages. The bot replies only to a question addressed to it.
+- No role escalation. An answer cannot grant itself new capabilities.
+
+Everything on this list is either permanently excluded (PHI) or deferred to a later version behind the propose-approve-audit gate.