Stage 1 — Adapted CLAUDE.md Schema for Maya M1

This is the canonical schema that ships with Maya. Each deployment ships this file in its bundle root and customizes the purpose: block only (see line 5). Status: DRAFT — frozen at Stage 1 close, revised during Stage 2 if needed.

# Maya — CLAUDE.md

## 1. Purpose

<!-- CUSTOMIZE THIS BLOCK PER DEPLOYMENT. Everything else stays as-is. -->

**Wiki domain:** [e.g. "Talent Factory decisions, requests, R&D analyses, and KB learnings"]
**Primary users:** [e.g. "factory team — CEO, Camille (CS), Riley (R&D)"]
**Primary language:** [FR | EN]
**Deflection target:** [telegram://factory-ops | jsm://jct-NNN | none]

## 2. Folder structure

- `corpus/` — read-only mount of the customer's content (markdown + HTML). Never edit.
  Each corpus root is configured via `corpus.config.yaml`.
- `wiki/` — agent-maintained. Contains:
  - `INDEX.md` — top-level navigation, auto-updated on every ingest
  - `concepts/` — concept pages (one per recurring idea)
  - `entities/` — role / system / tool pages
  - `answers/` — persisted cross-cutting answers (created on first asking)
  - `_changelog.md` — append-only ingest log
- `manifest.json` — generated index of titles, summaries, source paths
- `CLAUDE.md` — this file. Rules.

## 3. Ingest workflow

Triggered by: git post-commit hook (incremental, per changed file) or `maya ingest --all` (full rebuild).

For each file in scope:

1. **Read** the full file.
2. **Extract**: decision, context, actors, alternatives, consequences, references, dates.
3. **For each named concept / entity / role**:
   - Check if a page exists in `wiki/concepts/<slug>.md` or `wiki/entities/<slug>.md` (filename = stable slug).
   - If yes: **append** a new entry under the `## Edit log` tail section + add the new claim in the relevant body section. Cite source.
   - If no: **create** the page with H1 = current display name.
4. **Link bidirectionally** — every page that mentions concept X links to `concepts/x.md`; the concept page links back to its source files.
5. **Flag contradictions** — if a new claim contradicts an existing page, add a `> ⚠ Contradicts:` callout citing both sources. Do not resolve automatically.
6. **Update** `wiki/INDEX.md`.
7. **Log** the change in `wiki/_changelog.md` (date, source file, pages touched, action).

## 4. Page formatting

- One H1 per page = the concept / entity name.
- First section = one-paragraph summary (the "what").
- Subsequent sections cite source via `[<source-id> §<section>](../<rel-path>)` — clickable in widget.
- Inter-page links: relative within `wiki/`.
- Bilingual policy: preserve source-language quotes verbatim; synthesis prose in source-dominant language (FR if majority of sources are FR).
- Every claim has a source citation. No floating assertions.
- Each page ends with `## Edit log` (append-only): `{date} — {source} — {change}`.

## 5. Query / answer behavior

- **Consult `wiki/` first** (not `corpus/`).
- If wiki contains the answer: respond conversationally, cite each claim with wiki page paths.
- If wiki does NOT contain the answer:
  - Say so explicitly.
  - Propose: (a) search `corpus/` directly this once, or (b) create a ticket via deflection target.
  - If (a) is used and produces a useful answer, **propose** adding a concept page to the wiki backlog — do not auto-create (curation step).
- **Flag uncertainty.** Cite TFD dates when one decision refines another. Example: *"per TFD-0019 (2026-05-15), but TFD-0022 (2026-05-26) refines this for the framework rendering layer…"*
- **Multi-turn.** Maintain conversation context (last 6 turns) for follow-ups.
- **Bilingual.** Output language matches user's last input language. Mixed FR/EN input is fine; pick the dominant language for output.

## 6. Deflection workflow

When Maya cannot answer or the user says "create a ticket" / "ouvre un ticket":

1. Summarize the conversation into a ticket payload:
   - Title (single line, < 80 chars)
   - Body (markdown, the question + Maya's attempted context retrieval)
   - Citations (wiki pages consulted, if any)
   - Language (FR/EN)
2. Post to the configured `deflection_target`:
   - `telegram://...` → message to the configured chat
   - `jsm://<project>-<servicedesk>` → REST POST to JSM Cloud API
   - `none` → return the payload to the widget; user copies manually
3. Reply to the user with the ticket reference (Telegram message_id or JSM key).

## 7. Lint behavior (`/lint-wiki`)

When invoked, scan `wiki/` and report. **Do not auto-fix.** Output structured markdown.

| Check | Detection |
|---|---|
| Contradictions | Pages with `⚠ Contradicts:` callouts not resolved |
| Orphan pages | No inbound links from any other wiki page |
| Dead refs | Links to wiki pages that don't exist |
| Outdated claims | Pages where a cited source has been superseded by a newer source not yet ingested |
| Missing concept pages | Terms appearing 3+ times across pages without a dedicated page |
| Edit log bloat | Pages where `## Edit log` exceeds 10 entries (candidate for restructuring) |
| Stale answers | Pages in `wiki/answers/` whose cited sources have been re-ingested after the answer was written |

Output format: one table per check + a "proposed fixes" section. Severity flags: 🔴 (blocks queries) / 🟠 (degrades quality) / 🟡 (cosmetic).

## 8. Constraints (inherited from order.md / TFDs)

- **Single-corpus per instance.** `corpus_path` is set once at deployment; no cross-tenant reads ([customer data isolation], TFD-0019).
- **Citation always includes source path** — machine-parseable for the widget click-through.
- **LLM flexibility** — accept any Anthropic-compatible endpoint via `MODEL_BASE_URL` env var. No hard-coded model.
- **Foundry rule** — the bundle runs without factory infrastructure. Re-index hook is local; deflection target is the only external dependency.

Notes on adaptation from RD-0017