Proactive guidance to avoid validation errors. Use before capture_installation
or update_cobie so you get the schema and steps right the first time.

Call this before capture_installation or update_cobie to validate your input
and avoid validation errors. Or call get_update_workflow() for the full checklist.

Checks:
- Target entity (SheetName + RowName) exists
- Category exists in PickList.DocumentType
- ApprovalBy exists in PickList.ApprovalBy
- Stage exists in PickList.StageType

Returns validation result with errors or success message.

Proactive validation: calls validate_document_input internally before writing.

Args:
    excel_path: Path to COBie Excel file
    name: Unique document identifier (e.g. 'DOC-2026-001')
    sheet_name: Target sheet (Component, Type, Space, Floor, etc.)
    row_name: Target entity name (must exist in target sheet)
    category: Document type from PickList.DocumentType
    approval_by: Approver from PickList.ApprovalBy
    stage: Stage from PickList.StageType
    directory: File directory path or 'n/a'
    file: File name or 'n/a'
    description: Document description (default 'n/a')
    reference: External reference URL (default 'n/a')
    actor_contact: Contact creating the document (CreatedBy)
    as_of_date: Creation date (defaults to today)
    dry_run: Preview changes without writing

Returns:
    Result with success status, created row number, and any errors.

Example:
    add_document(
        excel_path="project.xlsx",
        name="DOC-AHU1-MANUAL",
        sheet_name="Component",
        row_name="AHU-1",
        category="Operation and Maintenance",
        approval_by="Information Only",
        stage="As Built",
        directory="/docs/equipment",
        file="AHU-1-manual.pdf",
        description="Equipment operation manual",
        actor_contact={"email": "user@company.com", "company": "ACME", "phone": "555-1234", "category": "CM"}
    )

Returns name, description, version_hash for each skill. Use get_runtime_skill(name)
for full body; suggest_runtime_skill(user_intent, state) to route user intent
(e.g. pending_preview_id + 'confirm' → applying-updates).

Returns name, description, body_md, version_hash, sections. Use list_runtime_skills()
to discover names; suggest_runtime_skill(user_intent, state) to pick a skill from intent.

Deterministic heuristics: pending_preview + 'confirm' → applying-updates;
'export' → exporting-cobie; 'validate' → validating-cobie; default → editing-cobie.
Returns name and rationale. Use get_runtime_skill(name) for full body.

Target path: {docs_root}/{SheetName}/{RowName}/{filename}

Returns the Directory and File values to pass to add_document.
Use this to physically organize documents before adding metadata to Excel.

Args:
    source_file_path: Path to source file
    sheet_name: Target sheet (Component, Type, Space, etc.)
    row_name: Target entity name
    docs_root: Base folder for document organization
    copy: If True, copy file (default). If False, move file.
    filename_override: Optional filename to use instead of original

Returns:
    Dictionary with directory, file, target_path, and success status

Example:
    result = organize_document_file(
        source_file_path="/tmp/AHU-1-manual.pdf",
        sheet_name="Component",
        row_name="AHU-1",
        docs_root="project_docs"
    )
    # Returns: {"directory": "project_docs/Component/AHU-1", "file": "AHU-1-manual.pdf"}
    # Then use in add_document

Does not touch the file system. Use when organizing manually or to preview paths.

Args:
    sheet_name: Target sheet (Component, Type, Space, etc.)
    row_name: Target entity name
    filename: File name
    docs_root: Base folder for document organization (default 'docs')

Returns:
    Dictionary with recommended directory and file paths

Example:
    result = suggest_document_path(
        sheet_name="Component",
        row_name="AHU-1",
        filename="manual.pdf"
    )
    # Returns: {"directory": "docs/Component/AHU-1", "file": "manual.pdf"}

For filtered lists by floor/space use list_floors, list_spaces, list_components.

Args:
    entity_type: contact|space|floor|type|component|document (plural accepted).
    excel_path: Path to COBie Excel file.
    query: Optional text to match in any cell (case-insensitive substring).
    limit: Max items to return (default 50).

Returns:
    items (list of {id, label, key, sheet, rowIndex, fields}), executed_at, provenance.

Example:
    search_entities("component", "project.xlsx", query="AHU", limit=10)
    # items[].id = "component:AHU-1", items[].fields = {Name, TypeName, ...}

Returns consistent structured output with confidence and provenance.
On failure returns actionable error message; on partial failure (e.g. table
extraction fails) returns best-effort text and warnings. Output is kept
minimal: text_summary is provided when text is long; use full text when needed.

Args:
    text_path: Path to the text file
    mode: Extraction mode (currently only 'content' supported)

Returns:
    Dictionary with content, word_count, line_count, and key_phrases

Args:
    excel_path: Path to the Excel file
    limit_rows: Maximum rows to preview per sheet

Returns:
    Dictionary with sheet names, highlights, and row counts

**Read-only** (writes HTML report to disk only). Use after commit to revalidate.

**Safety:** No confirm_token on server. Client calls this to revalidate after
update_cobie/capture_installation commit.

Args:
    excel_path: Path to the COBie Excel file.

Returns:
    ValidationToolResult with summary (error/warning counts), html_path,
    status (ok|error), provenance, next_actions.

Example:
    result = validate_cobie("project.xlsx")
    # result.summary = {"total_fail": 0, "total_pass": 12, ...}
    # result.html_path = "project.validation.html"
    # result.status = "ok" | "error"
    # result.next_actions = ["Fix reported rows and re-run validate_cobie.", ...]

Applies the draft to a temporary copy, runs COBie validation, and returns status/summary.
Use before commit to block Apply when the result would be invalid. Read-only for the
original workbook; temp file is always deleted.

Args:
    excel_path: Path to the COBie Excel file.
    structured_update_json: Draft in UpdateRequest shape (instructions array).
    actor_contact: Optional; if omitted, a system placeholder is used for stamping.

Returns:
    ValidateDraftResult: status (ok|error), summary (total_fail, total_pass, ...),
    executed_at, next_actions, optional results.

Read-only. Use when the user asks "what's missing", "is this ready", or "correct this record"
and an entity (sheet + key) is in context.

Args:
    excel_path: Path to the COBie Excel file.
    sheet: Optional sheet name (e.g. "Component", "Type") to filter by entity.
    key: Optional row key (e.g. component Name) to filter by entity.

Returns:
    HandoverReadinessResult: ready, missing_required, invalid_refs, warnings,
    summary, suggested_instructions (simple deterministic fix suggestions).

Update COBie workbook with structured instructions or natural language text.

**Before first update:** Call get_update_workflow() or get_actor_contact_schema() to get
the required structure and avoid validation errors. Use MCP prompt 'how_to_update_cobie' for the full guide.

**IMPORTANT - File Modification Behavior:**
- **DEFAULT (output_path=None):** Edits the original file IN-PLACE (modifies excel_path directly)
- **With output_path:** Creates a NEW file at output_path, leaves original untouched
- **With create_backup=True:** Creates "excel_path.bak" backup before editing in-place

**Use Cases:**
- Normal editing: Don't specify output_path (edits original)
- Create a modified copy: Specify output_path
- Safe editing with backup: Set create_backup=True

**Actor contact (required):** Provide updater identity to stamp CreatedBy/CreatedOn.
{
    "email": "john@example.com",
    "company": "ACME Corp",
    "phone": "555-1234",
    "category": "Installer"
}

**Input format:** Use EITHER instruction_text OR structured_update_json (not both).

**instruction_text format (natural language):**
- "Update <ComponentName> <FieldName> to <value>"
Examples:
- "Update Tap-1 InstallationDate to 2026-02-16"
- "Update Pump-3A SerialNumber to SN-12345"
- "Update DR:T1A Material to Steel"

**structured_update_json format:**
{
    "instructions": [
        {
            "component_name": "Tap-1",
            "attribute_name": "InstallationDate",
            "new_value": "2026-02-16",
            "target_sheet": "Component",
            "target_key": "Tap-1"
        }
    ]
}

**Common mistakes:**
- Field names are case-sensitive: use lowercase 'email', 'company', 'phone', 'category'
- Provide ALL required actor_contact fields at once (not gradually)
- Don't specify output_path unless you want to create a separate copy

**Safety (commit gate):** Call with dry_run=False only after user has confirmed
the preview. No confirm_token on server; client must enforce confirm_token (e.g.
CONFIRM_APPLY). After commit, call validate_cobie(excel_path) to revalidate.

Example (preview):
    update_cobie(excel_path, structured_update_json={"instructions": [...]},
                 actor_contact=actor, dry_run=True, diff=True)
    # Returns: success, updated_count, errors, diffs, summary, next_actions
Example (commit, after user confirm):
    update_cobie(excel_path, structured_update_json={"instructions": [...]},
                 actor_contact=actor, dry_run=False)

**Preview gate:** Use this before apply. To commit, call update_cobie with
dry_run=False only after user confirmation (e.g. confirm_token CONFIRM_APPLY).
No confirm_token on server; client enforces confirm_token.

Args:
    excel_path: Path to COBie Excel file.
    draft_json: Same shape as structured_update_json for update_cobie (instructions array).
    actor_contact: Updater identity (required).
    as_of_date: Optional date for CreatedOn/InstallationDate.
    key_mode: Lookup mode for keys.

Returns:
    UpdateResult with success, updated_count, diffs, summary, next_actions, dry_run=True.

Example:
    result = preview_update("project.xlsx", {"instructions": [...]}, actor_contact)
    # result.diffs = [{"sheet": "Component", "row_key": "C-1", "column": "SerialNumber", ...}]
    # result.next_actions = ["To commit: call update_cobie with dry_run=False after confirm_token"]

Capture equipment installation data in the COBie workbook (construction phase).

**Before first use:** Call get_update_workflow() or get_actor_contact_schema() to get
the required actor_contact structure. Use MCP prompt 'how_to_update_cobie' for the full guide.

**IMPORTANT - File Modification Behavior:**
- **DEFAULT (output_path=None):** Edits the original file IN-PLACE (modifies excel_path directly)
- **With output_path:** Creates a NEW file at output_path, leaves original untouched
- **With create_backup=True:** Creates "excel_path.bak" backup before editing in-place

**Construction phase** (typical): Component name, type, and location are already in the
workbook from design. Only provide:
- component_identifier (required): The component name (e.g. "Tap-1", "DR:T1A")
- installation_date (optional): Use "today" or "now" when user says "just installed"
  **OR** use as_of_date parameter (if payload lacks installation_date, as_of_date is used automatically)
- serial_number, status (optional)
Do NOT ask for type, floor, or space—they are design-phase and already in the file.

**Payload fields:**
- component_identifier (required): Equipment name in the workbook
- installation_date (optional): ISO date, or "today"/"now" for current date.
  **NOTE:** If omitted and as_of_date parameter is provided, as_of_date will be used for InstallationDate.
- serial_number, status (optional): e.g. status="PLACED"|"STARTED"|"TESTED"|"COMMISSIONED"
- install_space, install_floor (optional): Only when adding NEW components; omit for
  construction phase—location comes from design.
- evidence_paths (optional): Paths to attach evidence files

**Actor contact (required):** Provide updater identity.
{
    "email": "john@example.com",
    "company": "ACME Corp",
    "phone": "555-1234",
    "category": "Installer"
}

**Minimal example (construction phase with as_of_date):**
{
    "payload": {
        "component_identifier": "Tap-1"
        # installation_date omitted - as_of_date will be used
    },
    "actor_contact": {
        "email": "installer@acme.com",
        "company": "ACME Corp",
        "phone": "555-1234",
        "category": "Installer"
    },
    "as_of_date": "2026-02-16"
}

**Alternative: explicit installation_date in payload:**
{
    "payload": {
        "component_identifier": "Tap-1",
        "installation_date": "today"
    },
    "actor_contact": {
        "email": "installer@acme.com",
        "company": "ACME Corp",
        "phone": "555-1234",
        "category": "Installer"
    }
}

**Common mistakes:**
- Use 'component_identifier', 'component_name', 'equipment_name', or 'ComponentName' (all accepted)
- Both snake_case and PascalCase (COBie standard) are accepted for payload fields
- Field names are case-sensitive: use lowercase 'email', 'company', 'phone', 'category'
- Provide ALL required actor_contact fields at once
- Don't specify output_path unless you want to create a separate copy

**Header requirements:** Workbook must have columns for any payload fields provided
(e.g. SerialNumber, InstallationDate, Status if you include them).

Requires confirm_token='CONFIRM_APPLY' unless dry_run=True.
Rejects applies when graph sync status is missing, stale, or error.