Project Structure

You are working on the Omni Suite — a 3-stage document localization pipeline: OPP (extract) → OL (translate) → ORF (backfill).

## Project Structure

```
Omni_Suite/
├── Omni_Pre_Processor/      # OPP — Document extraction (MD + XLIFF + skeleton)
│   └── src/opp/             # Source: detectors, extractors, pipeline
├── Omni_Localizer/          # OL — Translation (MD / XLIFF)
│   └── src/ol/              # Source: MD bus, XLIFF bus, repair layers
├── Omni_Re_Formatter/       # ORF — Backfill to target format
│   └── src/orf/             # Source: channels, converters, agents
├── tests/                   # Suite-level E2E tests (30+ files)
├── scripts/                 # setup_dev.sh, sync_shallow.sh, install_md2pptx.sh
├── .venv_ol/                # Unified venv (Python 3.13)
├── pyproject.toml           # Root workspace
├── .pre-commit-config.yaml  # Pre-commit hooks
├── Makefile                 # Dev targets (test, lint, clean, setup)
├── AGENTS.md                # Agent guidance (this file)
├── CLAUDE.md                # Claude Code architecture context
└── .cursorrules             # Cursor agent context (this file)
```

## Module Details

| Module | Path | CLI | MCP Server | Test Dir |
|--------|------|-----|------------|----------|
| OPP | `Omni_Pre_Processor/` | `opp` | `opp-mcp-server` | `Omni_Pre_Processor/tests/` |
| OL | `Omni_Localizer/` | `ol` | `ol-mcp` | `Omni_Localizer/tests/` |
| ORF | `Omni_Re_Formatter/` | `orf` | `orf-mcp-server` | `Omni_Re_Formatter/tests/` |

## MCP Server Names

Configure in your tool's MCP settings. **Note:** naming is not uniform —
`opp-mcp-server` and `orf-mcp-server` use the `-server` suffix, but `ol-mcp`
does NOT.

- `opp-mcp-server` — **9 tools**: `extract_document`, `batch_extract`, `detect_format_tool`, `generate_xliff`, `generate_markdown`, `save_skeleton`, `validate_xliff`, `ping`, `get_capabilities`
- `ol-mcp` (no `-server` suffix) — **21 tools**: `translate_md_text`, `translate_xliff`, `translate_file`, `batch_translate_texts`, `judge_text`, `load_glossary`, `get_relevant_terms`, `search_tm`, `add_tm_entries`, `verify_terms`, `extract_terms`, `shield_md_text`, `unshield_md_text`, `disambiguate`, `profile_doc`, `extract_warnings`, `generate_report`, `inspect_config`, `get_translation_status`, `ping`, `get_capabilities`
- `orf-mcp-server` — **7 tools**: `apply_md`, `apply_xliff`, `batch_convert`, `detect_format`, `info`, `ping`, `get_capabilities`

## MCP Path Allowlists

**Preferred**: Set `MCP_ALLOWED_DIRECTORIES` once — it is read by all 3 MCP servers (OPP, OL, ORF).

Per-module overrides (checked first, fall back to `MCP_ALLOWED_DIRECTORIES`):
- OPP: `OPP_MCP_ALLOWED_DIRS` (e.g. `/docs:/tmp/out`). **NOT** `OPP_ALLOWED_DIRECTORIES` (CLI-only).
- OL: `OL_ALLOWED_DIRECTORIES` (or configured in `ol_mcp/config.py`).
- ORF: `ORF_MCP_ALLOWED_DIRS` (defaults to `[Path.cwd()]` if unset — **production should always set it explicitly**).

OPP is fail-closed (`ValueError: allowed_directories cannot be empty` if unset).
ORF is fail-open (defaults to CWD). OL configures via file, not env.

## MCP stdio workaround (FastMCP 3.4.2 bug)

If MCP servers fail to respond to stdio JSON-RPC, use `scripts/mcp_bridge.py`
(raw JSON-RPC over stdin/stdout, no `mcp` library). See `../ACCEPTED_GAPS.md` line 18.

## CLI frameworks differ

- OPP: argparse (`opp`)
- OL: typer (`ol`)
- ORF: click (`orf`)

Flag names are uniform (`--kebab-case`). Help-text styles differ. See `../docs/DECISIONS.md` ADR 0001.

## Testing Conventions

- Always set `OMNI_TEST_FAKE_LLM=1` and `OMNI_TEST_FAKE_PANDOC=1` for offline test runs
- Python 3.13 via `.venv_ol/bin/python`
- Test markers: `nightly` (real LLM, skipped by default), `slow`, `e2e`, `requires_opp`, `requires_ol`, `requires_orf`
- Run `pytest tests/ -m "not nightly"` for quick suite checks
- Pre-commit hooks: `gitleaks`, `check-added-large-files`, `check-merge-conflict`, `detect-private-key`, `end-of-file-fixer`, `trailing-whitespace`, `omni-contract-smoke`

## Key Commands

```bash
source .venv_ol/bin/activate
make test-quick      # Quick suite check
make test            # Full CI-mode test run
make smoke           # Contract smoke test
make lint            # Pre-commit on all files
make clean           # Clean artifacts
```

## How to validate

Run the agent-testing validation engine (119 scenarios; no mocks, no
FAKE_LLM as evidence — tier-1 runs are hermetic). All commands from the
suite root with `.venv_ol`:

```bash
source .venv_ol/bin/activate

# Enumerate the library — no execution
python scripts/validation/run_validation.py --list

# Run one hermetic scenario (tier 1 = no LLM keys needed)
python scripts/validation/run_validation.py --scenario <name> --tier 1

# Contract-lint the library itself
python scripts/validation/run_validation.py --check
```

Only these scripts exist — do not invent other commands:
`scripts/validation/{run_validation.py, coverage_audit.py, validation_report.py, validation_diff.py, artifact_matrix.py, artifact_diff.py}`.

**Reading results**: `validation-runs/latest.txt` points at the newest
run (`validation-runs/<ts>/scenarios.json`). Generate the director
report with
`python scripts/validation/validation_report.py validation-runs/<ts>/scenarios.json`
→ `report.md` in the same dir, with TWO verdict families side by side:
**agent-user conformance** (tool-* scenarios + AGENT-SURFACE standards:
contract, JSON shape, error clarity, path security, exit codes) and
**human-quality conformance** (pipeline-* scenarios + HUMAN-QUALITY
standards: LQA ≥ 4.0/5, paragraph ratio ±5%, CJK density < 5%, zero
foreign punctuation, drawing count, opens in python-docx). `unconfigured`
(missing env, e.g. no LLM keys) is never a pass and never a silent skip.

**Standards**: `scenarios/STANDARDS.md` — the single citable bar, two
families, exact anchors per step (`standard: STANDARDS.md#<anchor>`).
Read it before judging a verdict.

**Director checklist**: a human director completes the 10-minute loop
per run — see `docs/dev/validation-director-loop.md` (agent validator +
human director roles, per-run standards conformance pass).