@iowarp/clio-coder 0.4.6 → 0.4.8

package/library/plugins/materio/assets/actions/literature-review.md

@@ -0,0 +1,199 @@
+# Action: literature-review
+
+This guide is linked from an installed portable skill. Action requests use the
+actual installed skill names; this standard package registers no slash commands.
+The interactive assistant applies a role inline or assigns its skill to a generic
+worker if the host supports delegation. No named worker registration is presumed.
+If a native peer package supplies command or agent bindings, follow its binding
+section below while preserving the same researcher gates and return checkpoints.
+
+This guide is linked from an installed portable skill. Determine the package root
+from that skill's directory. Before executing a shell example, bind PACKAGE_ROOT
+to that actual root in the same command. Treat $ARGUMENTS as validated user input;
+these are examples to fill with actual paths, not automatic host substitutions.
+
+
+
+Use the host's file reading/editing and local command execution capabilities. Read
+assets/references/research-policy.md, resolved from this package. If this task
+needs researcher answers, the interactive assistant asks them through the host's
+conversation facility before gated writes. Workers return questions with their
+checkpoint kind. Use the named role's portable skill for the scientific work;
+if the host does not support delegation, the interactive assistant performs that
+role with the same input/output and decision boundaries. Do not invent worker,
+search, fleet, or interactive capabilities. Inspect actual files before completion.
+Use package scripts by resolving their links from the installed skill directory.
+For an optional commit, set CHANGED_FILES to only the named files actually changed
+and read back during this action. The research-state helper rejects directory staging.
+
+
+Use the assigned role skill with complete research context and exact permitted outputs. Return structured checkpoints and inspect actual files after writing.
+
+<execution_context>
+@.research/RESEARCH.md
+@.research/config.json
+</execution_context>
+
+<objective>
+Conduct a structured literature review based on the research identity in RESEARCH.md. Identifies current state of knowledge, open gaps, key authors/groups, and proposes refined search keywords. Creates LITERATURE.md.
+
+**Orchestrator role:** Validate RESEARCH.md exists, gather the supplied corpus and scope guidance from the user, apply the materio-literature-reviewer skill, run the advisory citation check, collect the researcher's decisions on flagged entries and proposed keywords, handle loop-back to identify-research if a major problem with the prompt is found.
+
+**Why subagent:** Literature synthesis requires sustained reading, cross-referencing, and gap reasoning across many papers. Fresh context = more rigorous gap analysis. The agent never asks the researcher anything; every decision comes back here.
+</objective>
+
+<context>
+No arguments. Reads .research/RESEARCH.md and .research/config.json.
+</context>
+
+<process>
+
+Worker write scope: .research/LITERATURE.md.
+
+
+## 1. Gather Supplied Materials First
+
+Before any other research read, use ls on `.research/data/` and read
+`.research/DATA-INDEX.md`; inspect readable registered materials first. Record
+unreadable formats as access limits and ask for usable text when needed. Then
+validate the research identity and config below.
+
+### Validate Environment
+
+```bash
+test -f .research/RESEARCH.md || echo "ERROR: No RESEARCH.md. Run identify-research using the materio-research-explorer skill first."
+[ -f .research/LITERATURE.md ] && echo "WARN: LITERATURE.md exists. Running again will update it."
+cat .research/RESEARCH.md
+python3 "${PACKAGE_ROOT}/assets/scripts/research_state.py" config
+```
+
+## 2. Gather the Supplied Corpus
+
+```bash
+ls -la .research/data/ 2>/dev/null
+cat .research/DATA-INDEX.md 2>/dev/null
+```
+
+Supplied papers, BibTeX files, and notes are the primary corpus for the review; researcher-provided URLs may extend it. If nothing is registered, say so in the scope question below and offer `Run upload-data using the materio-research-explorer skill` first. Use only retrieval capabilities actually available. State that the review is built from supplied
+materials plus any specific URLs the researcher provides. Ask for those URLs in
+the scope question; use the host URL-fetch capability only when web_search is true and the tool is
+available. With web_search false, use supplied materials only. Record this exact
+coverage and access limits in LITERATURE.md under Sources Reviewed.
+
+## 3. Confirm Scope with User
+
+Use the host conversation facility:
+- header: "Literature Review Scope"
+- question: "I'll review literature based on your research prompt:\n\n**[research prompt from RESEARCH.md]**\n\nCorpus: [N] supplied files [list] · Provided-URL fetching: [allowed|disabled]\n\nAnything to adjust before I start?\n1. Any specific papers, authors, or groups to prioritize?\n2. Any journals or conferences to focus on?\n3. Year range? (default: all years, emphasis on last 10)\n4. Any sub-topics to explicitly include or exclude?\n5. Any specific URLs to add to the supplied corpus?"
+- options: "Start with current scope" | "I'll add more context" | "Upload papers first; Run upload-data using the materio-research-explorer skill"
+
+## 4. apply the materio-literature-reviewer skill
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ Materio ► REVIEWING LITERATURE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Apply the materio-literature-reviewer role skill using the assignment and full context; delegate if supported. The prompt carries:
+- `<research>`; full RESEARCH.md content
+- `<uploaded_data>`; every registered file path with its DATA-INDEX.md description
+- `<user_guidance>`; scope adjustments from Step 3
+- `<web_allowed>`; true only when config permits URL fetching and the host URL-fetch capability is available
+- `<provided_urls>`; the specific URLs supplied by the researcher, or none
+- `<literature_path>`; `.research/LITERATURE.md`
+
+## 5. Handle Agent Return
+
+**`literature_review_complete:`:**
+
+1. Use read on `.research/LITERATURE.md` and verify the file is on disk:
+   ```bash
+   test -s .research/LITERATURE.md && echo OK || echo "ERROR: LITERATURE.md missing"
+   ```
+   If missing, apply the role again and say so; do not continue.
+
+2. Advisory citation check. Verify the Key Papers table against Crossref to catch fabricated papers or dead DOIs. This is advisory; it never deletes anything on its own:
+   ```bash
+   if command -v python3 >/dev/null 2>&1; then
+     citation_flags=()
+     [ "$(python3 "${PACKAGE_ROOT}/assets/scripts/research_state.py" config --key web_search)" = true ] || citation_flags=(--offline)
+     if python3 "${PACKAGE_ROOT}/assets/scripts/verify_citations.py" "${citation_flags[@]}" .research/LITERATURE.md; then echo "CHECK EXIT: 0"; else echo "CHECK EXIT: $? (findings or incomplete coverage)"; fi
+   fi
+   ```
+   - If python3 is absent, record citation verification as skipped. If every entry is UNVERIFIABLE with network errors, record the access limitation in Review Notes and continue. With web_search false, run only the offline structural check.
+   - If any entry is **NOT_FOUND** or **MISMATCH**: show each flagged entry next to the closest Crossref match and ask via the host conversation facility, one batched question:
+     - header: "Citation Check"
+     - question: "Crossref could not confirm [N] entries:\n\n1. [entry] → closest match: [title, year, DOI] (score [x])\n2. ...\n\nFor each: keep as-is, mark unverified, correct to the match, or remove?"
+     - options: "Keep all, mark unverified" | "Correct to matches where shown" | "I'll decide per entry" | "Remove all flagged"
+     Apply the decision to LITERATURE.md. A flagged entry is never removed without the researcher saying so.
+
+3. Keyword gate. The agent proposed changes in the Refined Keywords section and in its return. Ask via the host conversation facility:
+   - header: "Keyword Refinement"
+   - question: "Based on the literature, I suggest refining keywords:\n\nAdd: [terms]\nRemove: [terms]\nReplace: [old] → [new]\n\nAny adjustments?"
+   - options: "Accept refined keywords" | "Keep original keywords" | "I'll adjust"
+   Apply the accepted set to the Keywords section of RESEARCH.md.
+
+4. Record (optional git):
+   ```bash
+   python3 "${PACKAGE_ROOT}/assets/scripts/research_state.py" record --message "research: literature review; [N] sources, [N] gaps identified" --files "${CHANGED_FILES[@]}"
+   ```
+
+**`loop_back:`:**
+- Read LITERATURE.md back and run the same advisory citation check and researcher decision gate above before applying the loop-back decision.
+- The reviewer found the prompt is too broad, too narrow, already answered, or rests on a false premise. LITERATURE.md was still written.
+- Present the finding and its three suggested prompts.
+- Ask via the host conversation facility:
+  - header: "Prompt Needs Revision"
+  - question: "The literature shows: [finding].\n\nSuggested revisions:\n1. [narrowed]\n2. [adjacent gap]\n3. [replication/extension]\n\nHow do you want to proceed?"
+  - options: "Narrow to suggestion 1" | "Narrow to suggestion 2" | "Narrow to suggestion 3" | "Proceed with the current prompt anyway"
+- If a suggestion is chosen: update the Selected Prompt and Key Decisions in RESEARCH.md and STATE.md, note the revision reason, then run the keyword gate above. If the change is larger than a rewording, recommend re-running `Run identify-research using the materio-research-explorer skill` with the new framing.
+
+**`needs_input: checkpoint:decision`, `needs_input: checkpoint:human-action`, or `needs_input: checkpoint:human-verify`:**
+- Present the question to the user, collect the answer via the host conversation facility, apply the role again.
+
+</process>
+
+<offer_next>
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ Materio ► LITERATURE REVIEW COMPLETE ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Review:   .research/LITERATURE.md
+Sources:  [N] supplied, [N] researcher-provided URLs fetched
+Gaps:     [N] identified
+Keywords: [primary keywords]
+Citations: [N verified, N marked unverified]
+
+───────────────────────────────────────────
+
+## ▶ Next Up
+
+**Map your available lab resources**
+(equipment, HPC, software, collaborations)
+
+`Run define-virtual-lab using the materio-lab-definer skill`
+
+<sub>Each dispatch starts with fresh worker context.</sub>
+
+───────────────────────────────────────────
+
+**Also available:**
+- `Run identify-research using the materio-research-explorer skill`; refine prompt based on gaps found
+- `Run upload-data using the materio-research-explorer skill`; add more papers/datasets to review
+- `Run define-research-tasks using the materio-workflow-planner skill`; skip virtual lab setup and go straight to workflow
+
+</offer_next>
+
+<success_criteria>
+- [ ] Every question to the researcher was asked by this command, not by the agent
+- [ ] Supplied corpus listed and passed to the agent; web availability passed explicitly
+- [ ] Current state of knowledge summarized by sub-topic
+- [ ] Evidence-supported gaps identified with limitations; zero gaps is a valid result
+- [ ] Key papers listed with quoted titles and provenance
+- [ ] Citation check run; flagged entries decided by the researcher, never auto-removed
+- [ ] Keywords refined only after the researcher accepted
+- [ ] Loop-back handled if the prompt needs revision
+- [ ] LITERATURE.md verified on disk; commit only if commit_research is true
+</success_criteria>

package/library/plugins/materio/assets/actions/pause-research.md

@@ -0,0 +1,34 @@
+# Action: pause-research
+
+This guide is linked from an installed portable skill. Action requests use the
+actual installed skill names; this standard package registers no slash commands.
+The interactive assistant applies a role inline or assigns its skill to a generic
+worker if the host supports delegation. No named worker registration is presumed.
+If a native peer package supplies command or agent bindings, follow its binding
+section below while preserving the same researcher gates and return checkpoints.
+
+This guide is linked from an installed portable skill. Determine the package root
+from that skill's directory. Before executing a shell example, bind PACKAGE_ROOT
+to that actual root in the same command. Treat $ARGUMENTS as validated user input;
+these are examples to fill with actual paths, not automatic host substitutions.
+
+
+
+Use the host's file reading/editing and local command execution capabilities. Read
+assets/references/research-policy.md, resolved from this package. If this task
+needs researcher answers, the interactive assistant asks them through the host's
+conversation facility before gated writes. Workers return questions with their
+checkpoint kind. Use the named role's portable skill for the scientific work;
+if the host does not support delegation, the interactive assistant performs that
+role with the same input/output and decision boundaries. Do not invent worker,
+search, fleet, or interactive capabilities. Inspect actual files before completion.
+Use package scripts by resolving their links from the installed skill directory.
+For an optional commit, set CHANGED_FILES to only the named files actually changed
+and read back during this action. The research-state helper rejects directory staging.. Inspect WORKFLOW.md, STATE.md, and
+actual partial task files. Record the active task, completed preparation, pending
+physical work, decisions, missing inputs, and exact next action. Mark the task
+paused without changing its identity or claiming unfinished results. Confirm any
+missing continuation details with the host conversation facility. Read the updated documents back.
+Run `python3 "${PACKAGE_ROOT}/assets/scripts/research_state.py" checkpoint save paused` and
+verify its receipt. Offer resume-research and show the saved continuation. If
+optional recording is enabled, pass only the changed named files to record.

package/library/plugins/materio/assets/actions/progress.md

@@ -0,0 +1,125 @@
+# Action: progress
+
+This guide is linked from an installed portable skill. Action requests use the
+actual installed skill names; this standard package registers no slash commands.
+The interactive assistant applies a role inline or assigns its skill to a generic
+worker if the host supports delegation. No named worker registration is presumed.
+If a native peer package supplies command or agent bindings, follow its binding
+section below while preserving the same researcher gates and return checkpoints.
+
+This guide is linked from an installed portable skill. Determine the package root
+from that skill's directory. Before executing a shell example, bind PACKAGE_ROOT
+to that actual root in the same command. Treat $ARGUMENTS as validated user input;
+these are examples to fill with actual paths, not automatic host substitutions.
+
+
+
+Use the host's file reading/editing and local command execution capabilities. Read
+assets/references/research-policy.md, resolved from this package. If this task
+needs researcher answers, the interactive assistant asks them through the host's
+conversation facility before gated writes. Workers return questions with their
+checkpoint kind. Use the named role's portable skill for the scientific work;
+if the host does not support delegation, the interactive assistant performs that
+role with the same input/output and decision boundaries. Do not invent worker,
+search, fleet, or interactive capabilities. Inspect actual files before completion.
+Use package scripts by resolving their links from the installed skill directory.
+For an optional commit, set CHANGED_FILES to only the named files actually changed
+and read back during this action. The research-state helper rejects directory staging.
+
+
+<execution_context>
+@.research/STATE.md
+@.research/WORKFLOW.md
+@.research/RESEARCH.md
+</execution_context>
+
+<objective>
+Display a rich progress report with statusline, recent task completions, current position, and routing to the next action. Equivalent to wtf-p action progress but for research workflow.
+</objective>
+
+<process>
+
+## 1. Validate
+
+```bash
+[ ! -f .research/RESEARCH.md ] && echo "No research project. Run identify-research using the materio-research-explorer skill." && exit 0
+cat .research/STATE.md 2>/dev/null
+cat .research/WORKFLOW.md 2>/dev/null
+cat .research/RESEARCH.md 2>/dev/null | head -20
+```
+
+## 2. Build Statusline
+
+```
+Materio ► [N]/[total] tasks ◆ [phase: exploring|reviewing|executing|writing] ► [domain]
+```
+
+Display this first, before all other output.
+
+## 3. Calculate Progress Metrics
+
+From WORKFLOW.md, count:
+- Total active tasks
+- Complete tasks (☑ complete)
+- In-progress tasks
+- Pending tasks
+- Archived tasks
+
+Determine current phase:
+- No LITERATURE.md → "exploring"
+- LITERATURE.md exists, no WORKFLOW.md → "reviewing"
+- WORKFLOW.md exists, tasks pending → "executing"
+- All tasks complete → "writing"
+
+## 4. Show Recent Work
+
+Find task output files modified in the last 7 days:
+```bash
+find .research/tasks/ -newer .research/RESEARCH.md -name "*.md" 2>/dev/null | head -5
+```
+
+Show 1-line summary of recent task completions.
+
+## 5. Display Progress Report
+
+```
+Materio ► [statusline]
+
+# [Research Prompt]
+
+**Phase:**    [exploring | reviewing | executing | writing]
+**Progress:** [████████░░] [N]/[total] tasks
+**Domain:**   [domain + sub-field]
+
+## Recent Work
+- Task [N] ([name]): [1-line output summary]
+
+## Current Position
+[Next pending task or current state]
+
+## Key Decisions Made
+[from STATE.md]
+
+## Open Questions
+[unresolved assumptions or decisions from WORKFLOW.md]
+```
+
+## 6. Route to Next Action
+
+**Phase = exploring:** → `Run literature-review using the materio-literature-reviewer skill`
+**Phase = reviewing:** → `Run define-virtual-lab using the materio-lab-definer skill` if VIRTUAL-LAB.md is missing, otherwise `Run define-research-tasks using the materio-workflow-planner skill`
+**Phase = executing, task in-progress:** → `Run execute-task using the materio-task-executor skill [N]`
+**Phase = executing, next pending task:** → `Run execute-task using the materio-task-executor skill `
+**Phase = writing:** → `Run wtfp using the materio-research-explorer skill` or `wtf-p action progress`
+
+Show the routed command clearly. If the researcher chooses it, follow its prompt flow with the existing context.
+
+</process>
+
+<success_criteria>
+- [ ] Statusline displayed first
+- [ ] Phase correctly determined
+- [ ] Task progress shown with counts and visual bar
+- [ ] Recent work summarized
+- [ ] Smart routing to next command
+</success_criteria>

package/library/plugins/materio/assets/actions/remove-task.md

@@ -0,0 +1,82 @@
+# Action: remove-task
+
+This guide is linked from an installed portable skill. Action requests use the
+actual installed skill names; this standard package registers no slash commands.
+The interactive assistant applies a role inline or assigns its skill to a generic
+worker if the host supports delegation. No named worker registration is presumed.
+If a native peer package supplies command or agent bindings, follow its binding
+section below while preserving the same researcher gates and return checkpoints.
+
+This guide is linked from an installed portable skill. Determine the package root
+from that skill's directory. Before executing a shell example, bind PACKAGE_ROOT
+to that actual root in the same command. Treat $ARGUMENTS as validated user input;
+these are examples to fill with actual paths, not automatic host substitutions.
+
+
+
+Use the host's file reading/editing and local command execution capabilities. Read
+assets/references/research-policy.md, resolved from this package. If this task
+needs researcher answers, the interactive assistant asks them through the host's
+conversation facility before gated writes. Workers return questions with their
+checkpoint kind. Use the named role's portable skill for the scientific work;
+if the host does not support delegation, the interactive assistant performs that
+role with the same input/output and decision boundaries. Do not invent worker,
+search, fleet, or interactive capabilities. Inspect actual files before completion.
+Use package scripts by resolving their links from the installed skill directory.
+For an optional commit, set CHANGED_FILES to only the named files actually changed
+and read back during this action. The research-state helper rejects directory staging.
+
+
+<execution_context>
+@.research/WORKFLOW.md
+</execution_context>
+
+<objective>
+Permanently remove a task from WORKFLOW.md after user confirmation. Use Run archive-task using the materio-research-explorer skill instead if you want to preserve it for reference.
+</objective>
+
+<context>
+Task number: $ARGUMENTS
+</context>
+
+<process>
+
+## 1. Validate
+
+```bash
+test -f .research/WORKFLOW.md || echo "ERROR: No WORKFLOW.md."
+[ -z "$ARGUMENTS" ] && echo "ERROR: Provide task number. Usage: Run remove-task using the materio-research-explorer skill 3" && exit 1
+cat .research/WORKFLOW.md
+```
+
+## 2. Show Task and Confirm
+
+Display the full task entry to be removed.
+
+**Check for dependents:** Find any tasks that list this task as a dependency. Warn the user if other tasks depend on the one being removed.
+
+Use the host conversation facility:
+- header: "Remove Task [N]: [name]?"
+- question: "This will permanently delete Task [N] from WORKFLOW.md.\n\n[full task block]\n\n[If dependents exist: WARNING; Tasks [X, Y] depend on this task. Removing it will break their dependency chain.]\n\nAlternative: `Run archive-task using the materio-research-explorer skill [N]` preserves it for reference.\n\nProceed with removal?"
+- options: "Yes, remove it" | "Archive it instead" | "Cancel"
+
+## 3. Remove Task from WORKFLOW.md
+
+Edit WORKFLOW.md to remove the task block. Update dependency references in other tasks if needed.
+
+## 4. Record
+
+Only if `commit_research` is true in `.research/config.json`:
+```bash
+python3 "${PACKAGE_ROOT}/assets/scripts/research_state.py" record --message "research: remove task [N]; [task name]" --files "${CHANGED_FILES[@]}"
+```
+
+</process>
+
+<success_criteria>
+- [ ] Task displayed before removal
+- [ ] Dependent tasks warned if applicable
+- [ ] User explicitly confirmed removal
+- [ ] Task block cleanly removed from WORKFLOW.md
+- [ ] Dependency references updated in remaining tasks
+</success_criteria>

package/library/plugins/materio/assets/actions/resume-research.md

@@ -0,0 +1,84 @@
+# Action: resume-research
+
+This guide is linked from an installed portable skill. Action requests use the
+actual installed skill names; this standard package registers no slash commands.
+The interactive assistant applies a role inline or assigns its skill to a generic
+worker if the host supports delegation. No named worker registration is presumed.
+If a native peer package supplies command or agent bindings, follow its binding
+section below while preserving the same researcher gates and return checkpoints.
+
+This guide is linked from an installed portable skill. Determine the package root
+from that skill's directory. Before executing a shell example, bind PACKAGE_ROOT
+to that actual root in the same command. Treat $ARGUMENTS as validated user input;
+these are examples to fill with actual paths, not automatic host substitutions.
+
+
+
+Use the host's file reading/editing and local command execution capabilities. Read
+assets/references/research-policy.md, resolved from this package. If this task
+needs researcher answers, the interactive assistant asks them through the host's
+conversation facility before gated writes. Workers return questions with their
+checkpoint kind. Use the named role's portable skill for the scientific work;
+if the host does not support delegation, the interactive assistant performs that
+role with the same input/output and decision boundaries. Do not invent worker,
+search, fleet, or interactive capabilities. Inspect actual files before completion.
+Use package scripts by resolving their links from the installed skill directory.
+For an optional commit, set CHANGED_FILES to only the named files actually changed
+and read back during this action. The research-state helper rejects directory staging.
+
+
+<objective>
+Load research state and resume from the last paused or in-progress task. Equivalent to wtf-p action progress but triggers active resumption.
+</objective>
+
+<process>
+
+## 1. Read State
+
+```bash
+cat .research/STATE.md 2>/dev/null
+cat .research/WORKFLOW.md 2>/dev/null
+```
+
+## 2. Find Paused or Next Pending Task
+
+Look for tasks with status `☐ paused` first, then `☐ pending`.
+
+Change `☐ paused` back to `☑ in-progress` if found.
+
+## 3. Show Resumption Context
+
+Display:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ Materio ► RESUMING RESEARCH
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Research:   [prompt]
+Resuming:   Task [N]; [name]
+Last saved: [timestamp from STATE.md]
+
+Task context:
+[full task block from WORKFLOW.md]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## 4. Update STATE.md
+
+Set status = "active", record the resume timestamp. Only if `commit_research` is true in `.research/config.json`:
+```bash
+python3 "${PACKAGE_ROOT}/assets/scripts/research_state.py" record --message "research: resume at task [N]; [task name]" --files "${CHANGED_FILES[@]}"
+```
+
+## 5. Offer Next Action
+
+Suggest: `Run execute-task using the materio-task-executor skill [N]` to continue, or `Run progress using the materio-research-explorer skill` for full overview.
+
+</process>
+
+<success_criteria>
+- [ ] Paused task identified and status restored to in-progress
+- [ ] Full task context shown to orient the user
+- [ ] STATE.md updated
+- [ ] Next command clearly offered
+</success_criteria>

package/library/plugins/materio/assets/actions/settings.md

@@ -0,0 +1,38 @@
+# Action: settings
+
+This guide is linked from an installed portable skill. Action requests use the
+actual installed skill names; this standard package registers no slash commands.
+The interactive assistant applies a role inline or assigns its skill to a generic
+worker if the host supports delegation. No named worker registration is presumed.
+If a native peer package supplies command or agent bindings, follow its binding
+section below while preserving the same researcher gates and return checkpoints.
+
+This guide is linked from an installed portable skill. Determine the package root
+from that skill's directory. Before executing a shell example, bind PACKAGE_ROOT
+to that actual root in the same command. Treat $ARGUMENTS as validated user input;
+these are examples to fill with actual paths, not automatic host substitutions.
+
+
+
+Use the host's file reading/editing and local command execution capabilities. Read
+assets/references/research-policy.md, resolved from this package. If this task
+needs researcher answers, the interactive assistant asks them through the host's
+conversation facility before gated writes. Workers return questions with their
+checkpoint kind. Use the named role's portable skill for the scientific work;
+if the host does not support delegation, the interactive assistant performs that
+role with the same input/output and decision boundaries. Do not invent worker,
+search, fleet, or interactive capabilities. Inspect actual files before completion.
+Use package scripts by resolving their links from the installed skill directory.
+For an optional commit, set CHANGED_FILES to only the named files actually changed
+and read back during this action. The research-state helper rejects directory staging.. Run
+`python3 "${PACKAGE_ROOT}/assets/scripts/research_state.py" config` and display effective values:
+web_search (default false, controls provided-URL fetching and Crossref queries),
+auto_checkpoint (default true), and commit_research (default false).
+Model and target selection belongs to the host's configured targets; no plugin setting
+silently changes host models. Supplied data lives at `.research/data/`.
+
+Ask with the host conversation facility which settings to change. Preserve unrelated existing config
+fields. Write only actual boolean values in .research/config.json, then run the
+config helper again and read the file back. Malformed configuration needs repair
+before dependent work. An existing authorization remains valid; do not repeatedly
+ask to reconfirm the same choice. Report the effective values and implications.