Update to MOOS-IvP Skills

{
  "description": "Consult MIT MOOS-IvP PDFs and local ivp/src for documentation-backed answers about apps, behaviors, parameters, concepts, upstream semantics, or doc-vs-source differences.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 346
    },
    {
      "relative_path": "assets/moos-ivp-logo.png",
      "size_in_bytes": 1328624
    },
    {
      "relative_path": "references/doc-selection.md",
      "size_in_bytes": 4811
    }
  ],
  "name": "moos-ivp-docs",
  "skill_md_contents": "---\nname: moos-ivp-docs\ndescription: \"Consult MIT MOOS-IvP PDFs and local ivp/src for documentation-backed answers about apps, behaviors, parameters, concepts, upstream semantics, or doc-vs-source differences.\"\n---\n\n# MOOS-IVP Docs\n\n## Overview\n\nUse this skill to ground MOOS-IvP answers in the live MIT manual PDFs and, when needed, the local `moos-ivp` source tree.\n\nRead `references/doc-selection.md` when you need the filename-family rules, alias map, repo discovery order, or source-inspection rules.\n\n## When To Use\n\nUse this skill when the task is about:\n- MOOS-IvP app or utility behavior\n- IvP behavior semantics or parameters\n- MOOS-IvP terminology, architecture, or conceptual questions\n- `.moos` or `.bhv` settings whose upstream meaning should be confirmed in the docs\n- comparing upstream documentation against a local `moos-ivp` checkout\n\n## When Not To Use\n\nDo not use this skill as the primary tool for:\n- `.alog` mission reconstruction or incident forensics\n- launching or tearing down missions\n- purely local code-editing tasks when no documentation question is involved\n\nIf the task is mainly about `.alog` evidence, use `moos-alog-analysis` first.\n\n## Authority Model\n\nApply this authority order:\n\n1. If the user explicitly asks for documentation, or if you are unsure about upstream MOOS-IvP behavior, use the MIT PDFs first. Do not answer from memory in this case.\n2. If the user asks what the current checkout actually does, inspect local `ivp/src` first and use MIT PDFs only as upstream context.\n3. If MIT docs and local source differ, say so explicitly and cite both.\n4. Do not widen to broader web sources in v1.\n\nTreat the MIT PDFs as the upstream source of truth for documented semantics when asked or when uncertain. Treat local `ivp/src` as the source of truth for checkout-specific implementation behavior.\n\n## MIT PDF Lookup Workflow\n\n1. Open the live MIT index at `https://oceanai.mit.edu/ivpman/pdfs/` first.\n2. Classify the question as one of:\n   - app or utility\n   - behavior\n   - conceptual or architecture\n   - tutorial or operator help\n3. Build a shortlist of 1 to 3 candidate PDFs from the live filenames only.\n   - For an exact app or utility name, prefer the matching `app_*` filename first if it exists, for example `uQueryDB` -> `app_uquerydb.pdf`.\n4. Open the best candidate first. If opening the PDF from the index fails, construct the direct PDF URL from the filename shown in the index and open that URL directly. If both attempts fail, treat that document as unavailable and either try another candidate or fall back to local source inspection.\n5. Use in-PDF search to verify the app name, behavior name, parameter, or topic appears in the document before relying on it.\n6. Open a second or third candidate only if the first document is incomplete, too general, or ambiguous.\n7. Answer with the selected PDF URL and line citations. If the PDF tool does\n   not provide stable line numbers, use `pdftotext -layout <pdf> - | nl -ba`\n   or an equivalent extraction artifact and label those as extracted-text line\n   spans rather than canonical PDF anchors.\n\nRepresentative pattern:\n\n- `uQueryDB` question: inspect the live index, shortlist `app_uquerydb.pdf`, verify `uQueryDB` appears inside the PDF, and only then fall back to local `ivp/src/uQueryDB` if the PDF is unavailable or incomplete.\n\nCritical rule:\n- Do not hard-default a conceptual question to a specific `chap_*` PDF before inspecting the live index and verifying the topic inside the PDF.\n\n## Local Repo Fallback Workflow\n\nUse local source inspection when:\n- the docs are unavailable\n- no clear PDF match exists\n- the PDF text is too weak to settle the question\n- the user asks what the current checkout actually does\n- the local checkout version is newer or more specific than the available MIT PDFs\n\nWhen local MOOS-IvP source is needed, resolve the checkout in this order:\n\n1. Path explicitly provided by the user.\n2. `MOOS_IVP_ROOT` from the shell environment.\n3. Active task workspace if it contains `ivp/src`.\n4. Parent or sibling directories near the active task workspace.\n5. Common home locations such as `~/moos-ivp`, `~/src/moos-ivp`, `~/repos/moos-ivp`, and `~/projects/moos-ivp`.\n6. A bounded shallow home search for a directory named `moos-ivp`, excluding noisy folders.\n\nPrefer explicit common-root checks before broad `find` searches. If a bounded\nhome search is needed on macOS or a permissions-noisy system, suppress expected\npermission noise, for example with `2>/dev/null`.\n\nValidate a candidate repo by confirming:\n- `ivp/src` exists\n- recognizable app or behavior directories exist under `ivp/src`\n\nIf local source is required and no valid checkout is found, stop and ask the user for the checkout path. Do not answer source-specific questions from memory or weaker evidence.\n\nIf multiple repos are found, prefer the current workspace repo when applicable. Otherwise prefer the repo nearest to the current working directory and state which repo you used.\n\nIf the checkout has a versioned app or behavior with no same-version PDF in the MIT index, treat local source as authoritative for that version-specific behavior and cite MIT docs only as the nearest upstream reference.\n\n## Citation Requirements\n\nWhen you use this skill:\n- cite the MIT PDF URL and PDF line spans when the docs path is used\n- cite local file paths and line spans when the source path is used\n- clearly label whether the answer is based on upstream documentation, local checkout source, or both\n- say explicitly when MIT docs did not fully settle the question and the answer was completed from source inspection\n\n## Conflict Handling\n\nIf docs and source disagree:\n- separate the upstream-doc answer from the checkout-specific answer\n- do not collapse them into a single blended claim\n- explain which source is authoritative for each part of the answer\n\n## Failure Modes\n\n- MIT index unavailable: fall back to local source inspection if a repo can be found\n- MIT index available but no clear PDF match: use local source if present, otherwise say no exact document was identified\n- PDF text extraction weak: use nearby lines or a second supporting PDF, but do not overstate certainty\n- repo not found: say that local source fallback was unavailable\n\n## Coordination With Other MOOS Skills\n\n- Use `moos-alog-analysis` first for existing `.alog` analysis. Bring this skill in only if documentation context would help interpret the findings.\n"
}