# Context Orchestration

This repo is smaller than `bloomreach-cli`. It should use the same principle, not the same full workspace machinery: route the task, load the smallest useful context, prefer readable summaries/cards when available, and use raw JSON only for exact selected-object facts.

The normal source of truth in this repo is:

- local business and strategy context under `contexts/`
- supplied `projectContext` / `projectContextJson` from Loomi MCP through Claude Code/Codex, another host agent, or a saved JSON file
- optional Bloomreach CLI generated workspace context only when those files are present or supplied

The canonical flow is Claude Code/Codex loading context, calling Loomi MCP for current project truth, and using this generator to produce the manual Bloomreach implementation plan.

## Canonical Flow

```mermaid
flowchart TD
  task["User task<br/>goal, segment, scenario, content, review, or symptom"]
  agents["AGENTS.md<br/>repo rules and safety"]

  subgraph Core["This repo context"]
    router["docs/agent-context/router.md<br/>task family and load rules"]
    overview["contexts/overview.md<br/>local context map"]
    team["contexts/team.md<br/>business facts and rules"]
    industry["contexts/industries/*.md<br/>industry playbooks"]
    platform["contexts/platforms/bloomreach.md<br/>Bloomreach strategy rules"]
    project["contexts/projects/*<br/>lightweight saved project context"]
  end

  subgraph Live["Supplied project evidence"]
    loomi["projectContextJson<br/>from Loomi MCP via Codex/Claude or file"]
  end

  subgraph OptionalCli["Optional Bloomreach CLI export"]
    workspaceRouter["context/context-router.md<br/>only if available"]
    searchIndex["context/search-index.json<br/>candidate IDs and names"]
    cards["context/cards/**/*.md<br/>selected readable cards"]
    raw["context/*.json#&lt;id-or-name&gt;<br/>selected raw fallback only"]
  end

  packet["Task packet<br/>goal, task family, loaded facts, scope, gaps"]
  generator["Generator tools<br/>brief, recommendations, scenario, content, solution pack"]
  output["Manual Bloomreach guidance<br/>scenario calls contentgen API at runtime"]

  task --> agents
  agents --> router
  router --> overview
  overview --> team
  overview --> industry
  overview --> platform
  overview --> project
  router --> loomi

  router -. "if CLI context exists" .-> workspaceRouter
  workspaceRouter --> searchIndex
  searchIndex --> cards
  cards -. "missing exact detail" .-> raw

  team --> packet
  industry --> packet
  platform --> packet
  project --> packet
  loomi --> packet
  cards -. "optional evidence" .-> packet
  raw -. "selected fallback" .-> packet

  packet --> generator
  generator --> output

  classDef manual fill:#fff7ed,stroke:#c2410c,color:#7c2d12
  classDef local fill:#eef2ff,stroke:#4f46e5,color:#312e81
  classDef evidence fill:#ecfeff,stroke:#0891b2,color:#164e63
  classDef optional fill:#f0fdf4,stroke:#16a34a,color:#14532d
  classDef rawClass fill:#f8fafc,stroke:#64748b,color:#334155,stroke-dasharray: 4 3

  class agents,router manual
  class overview,team,industry,platform,project local
  class loomi,packet,generator,output evidence
  class workspaceRouter,searchIndex,cards optional
  class raw rawClass
```

## Source Roles

- `AGENTS.md` defines repo rules, safety, and workflow expectations.
- `docs/agent-context/router.md` maps task families to context loading.
- `contexts/overview.md` is the entry point for the built-in local context library.
- `contexts/team.md`, industry packs, and project files are business and strategy context.
- `projectContextJson` is the normal live project evidence handoff into generator tools.
- Bloomreach CLI `context/` files are optional richer evidence. Do not require them for this repo to work.

## Operating Rules

1. Use local `contexts/` first for business, industry, platform, and lightweight saved project context.
2. Use `projectContextJson` when exact current Bloomreach project truth is supplied.
3. If a Bloomreach CLI `context/` export is available, use its router, search index, and cards to avoid loading broad raw JSON.
4. Open raw JSON only for the selected asset/object and only when exact IDs, node payloads, filters, schema fields, or config details are missing from readable context.
5. Build a task packet before calling generator tools: goal, task family, loaded files, exact facts, assumptions, scope, and missing context.
6. Pass only relevant context into generator tools. Do not dump every file into `projectContextJson`.

## Email Runtime Pattern

The generator does not create final email HTML or write Bloomreach assets. For email scenarios it outputs the pattern that the Bloomreach scenario should implement:

1. Trigger or enter the selected audience.
2. Call `POST https://cod-beta.solution-production.eu/contentgen/api/v1/generate` from a `per-customer-webhook-action`.
3. Pass campaign brief fields plus `event.language`, `event.price_affinity`, `event.product_type`, and `event.brand`.
4. Check `webhook.available == True`.
5. Store `webhook.cache_key` into `customer.customer_variant`.
6. Verify the generated content exists through the project cache snippet.
7. Send the dynamic email template using `catalogs.content.item_by_id(customer.customer_variant).content_json | from_json`.

The authorization value must come from a project variable or other approved secret storage. Do not paste bearer tokens into generated files or docs.

## Generator Boundary

This generator owns strategy, validation, output shape, and manual implementation guidance. Loomi MCP, the host agent, or optional Bloomreach CLI discovery owns live project data collection.

The generator must not create or update Bloomreach assets. It should produce reviewable, copy/paste-ready guidance and name any missing facts needed before implementation.