@iowarp/clio-coder 0.4.6 → 0.4.8

package/library/plugins/materio/ai.iowarp.clio/prompts/materio/literature-review.md

@@ -0,0 +1,201 @@
+---
+description: "Conduct literature review, identify research gaps, and define search keywords"
+---
+
+<clio_execution>
+Read ${component:resource:clio-execution} before acting. It defines argument parsing,
+research state helpers, interview ownership, readback, and optional recording.
+</clio_execution>
+
+<clio_dispatch>
+Select the named recipe with dispatch({agent:"materio-...", task:"assignment with
+full context and exact permitted outputs", intent:{write_roots:["exact/output"]}}).
+Replace the illustrative recipe/path with those stated in this command. Use the
+registered dispatch fields shown here.
+Read the recipe's bound skill references and inline required templates, domain
+sections, answers and selected state into the worker task. Each dispatch starts
+fresh: re-dispatch with the full original context, prior candidates/outputs and
+the new selection, corrections, revisions or resume answer. Use monitor if the
+returned run is still active. Do not infer a resumed transcript from a run ID.
+Honor admission refusals instead of broadening write scope.
+
+Agent returns are mutation-report JSON. Route on the beginning of summary using
+the status branches below. For checkpoints, distinguish
+`needs_input: checkpoint:decision`, `needs_input: checkpoint:human-action`, and `needs_input: checkpoint:human-verify`;
+ask the exact question(s), collect the answer and re-dispatch. No new top-level
+status fields are allowed. A conforming JSON result is not proof of completion.
+After EVERY dispatch that wrote, use ls and read on every reported output and on
+the command's required files, including loop_back and partial checkpoint returns.
+Verify nonempty content and the promised changes before presenting success or
+continuing; re-dispatch with any missing/incorrect file named. Treat actual failed
+validation or execution as failure even when summary claims completion.
+</clio_dispatch>
+
+<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, spawn the materio-literature-reviewer agent, 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 /materio:identify-research first."
+[ -f .research/LITERATURE.md ] && echo "WARN: LITERATURE.md exists. Running again will update it."
+cat .research/RESEARCH.md
+python3 "${component:script:research-state}" 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 `/materio:upload-data` first. Clio has no web search tool. 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 web_fetch 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 ask_user:
+- 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; /materio:upload-data"
+
+## 4. Spawn materio-literature-reviewer Agent
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ Materio ► REVIEWING LITERATURE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Use dispatch with `agent: "materio-literature-reviewer"` and a task containing the assignment and full context. 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 web_fetch 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, re-dispatch the agent 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 "${component:script:research-state}" config --key web_search)" = true ] || citation_flags=(--offline)
+     if python3 "${pluginRoot}/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 ask_user, 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 ask_user:
+   - 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 "${component:script:research-state}" 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 ask_user:
+  - 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 `/materio:identify-research` 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 ask_user, re-dispatch the agent.
+
+</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)
+
+`/materio:define-virtual-lab`
+
+<sub>Each dispatch starts with fresh worker context.</sub>
+
+───────────────────────────────────────────
+
+**Also available:**
+- `/materio:identify-research`; refine prompt based on gaps found
+- `/materio:upload-data`; add more papers/datasets to review
+- `/materio:define-research-tasks`; 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/ai.iowarp.clio/prompts/materio/pause-research.md

@@ -0,0 +1,12 @@
+---
+description: Save the current research position and pause active work.
+---
+
+Read ${component:resource:clio-execution}. 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 ask_user. Read the updated documents back.
+Run `python3 "${component:script:research-state}" 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/ai.iowarp.clio/prompts/materio/progress.md

@@ -0,0 +1,105 @@
+---
+description: "Show research progress with statusline, recent work, and smart routing to next action"
+---
+
+<clio_execution>
+Read ${component:resource:clio-execution} before acting. It defines argument parsing,
+research state helpers, interview ownership, readback, and optional recording.
+</clio_execution>
+
+<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 /wtfp:progress but for research workflow.
+</objective>
+
+<process>
+
+## 1. Validate
+
+```bash
+[ ! -f .research/RESEARCH.md ] && echo "No research project. Run /materio:identify-research." && 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:** → `/materio:literature-review`
+**Phase = reviewing:** → `/materio:define-virtual-lab` if VIRTUAL-LAB.md is missing, otherwise `/materio:define-research-tasks`
+**Phase = executing, task in-progress:** → `/materio:execute-task [N]`
+**Phase = executing, next pending task:** → `/materio:execute-task [N+1]`
+**Phase = writing:** → `/materio:wtfp` or `/wtfp: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/ai.iowarp.clio/prompts/materio/remove-task.md

@@ -0,0 +1,63 @@
+---
+description: "Remove a task from the research workflow permanently"
+argument-hint: "[task number N]"
+---
+
+<clio_execution>
+Read ${component:resource:clio-execution} before acting. It defines argument parsing,
+research state helpers, interview ownership, readback, and optional recording.
+</clio_execution>
+
+<execution_context>
+@.research/WORKFLOW.md
+</execution_context>
+
+<objective>
+Permanently remove a task from WORKFLOW.md after user confirmation. Use /materio:archive-task 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: /materio:remove-task 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 ask_user:
+- 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: `/materio:archive-task [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 "${component:script:research-state}" 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/ai.iowarp.clio/prompts/materio/resume-research.md

@@ -0,0 +1,64 @@
+---
+description: "Resume research from a paused state; shows current position and suggests next action"
+---
+
+<clio_execution>
+Read ${component:resource:clio-execution} before acting. It defines argument parsing,
+research state helpers, interview ownership, readback, and optional recording.
+</clio_execution>
+
+<objective>
+Load research state and resume from the last paused or in-progress task. Equivalent to /wtfp: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 "${component:script:research-state}" record --message "research: resume at task [N]; [task name]" --files "${CHANGED_FILES[@]}"
+```
+
+## 5. Offer Next Action
+
+Suggest: `/materio:execute-task [N]` to continue, or `/materio:progress` 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/ai.iowarp.clio/prompts/materio/settings.md

@@ -0,0 +1,16 @@
+---
+description: Inspect or update research network, checkpoint, and commit settings.
+---
+
+Read ${component:resource:clio-execution}. Run
+`python3 "${component:script:research-state}" 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 Clio's configured targets; no plugin setting
+silently changes host models. Supplied data lives at `.research/data/`.
+
+Ask with ask_user 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.

package/library/plugins/materio/ai.iowarp.clio/prompts/materio/status.md

@@ -0,0 +1,92 @@
+---
+description: "Show full research project dashboard; identity, workflow progress, data, and next action"
+---
+
+<clio_execution>
+Read ${component:resource:clio-execution} before acting. It defines argument parsing,
+research state helpers, interview ownership, readback, and optional recording.
+</clio_execution>
+
+<objective>
+Display a concise dashboard of the current materio research project. No subagents; reads files directly and formats output.
+</objective>
+
+<process>
+
+## 1. Check Initialization
+
+```bash
+[ ! -f .research/RESEARCH.md ] && echo "No research project initialized. Run /materio:identify-research to start." && exit 0
+```
+
+## 2. Read All State Files
+
+```bash
+cat .research/RESEARCH.md
+cat .research/LITERATURE.md 2>/dev/null | head -30
+cat .research/WORKFLOW.md 2>/dev/null
+cat .research/STATE.md 2>/dev/null
+cat .research/DATA-INDEX.md 2>/dev/null | head -20
+ls .research/tasks/ 2>/dev/null
+ls .research/data/ 2>/dev/null
+ls .planning/ 2>/dev/null | head -5
+ls .research/handoff/ 2>/dev/null
+ls -1t .research/checkpoints/ 2>/dev/null | head -3
+```
+
+## 3. Display Dashboard
+
+Format and display:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ Materio RESEARCH STATUS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+RESEARCH IDENTITY
+  Prompt:   [research prompt from RESEARCH.md]
+  Domain:   [domain + sub-field]
+  Stage:    [career stage]
+
+LITERATURE
+  Status:   [LITERATURE.md exists? complete | pending]
+  Gaps:     [N gaps identified]
+  Keywords: [primary keywords]
+
+VIRTUAL LAB
+  Status:   [VIRTUAL-LAB.md exists? defined | not defined]
+  Equipment:[N items] | Compute: [HPC systems] | Gaps: [N flagged]
+
+WORKFLOW  ([N]/[total] tasks complete)
+  Task 01:  [name]; [☑ complete | ☑ in-progress | ☐ pending | ☐ archived]
+  Task 02:  [name]; [status]
+  ...
+
+DATA
+  [N] files registered (.research/DATA-INDEX.md)
+  [N] files in .research/data/
+
+PAPER (wtf-p)
+  [.planning/project.json → "wtf-p 0.6 project initialized" |
+   other existing .planning files → "existing paper state; inspect compatibility" |
+   .research/handoff/ → "Handoff written; paste into wtf-p" |
+   "Not started; use /materio:wtfp"]
+
+───────────────────────────────────────────
+▶ SUGGESTED NEXT ACTION
+  [smart routing based on state]
+───────────────────────────────────────────
+```
+
+## 4. Smart Next Action
+
+Based on state, suggest:
+- No RESEARCH.md → `/materio:identify-research`
+- No LITERATURE.md → `/materio:literature-review`
+- No VIRTUAL-LAB.md → `/materio:define-virtual-lab`
+- No WORKFLOW.md → `/materio:define-research-tasks`
+- Tasks pending → `/materio:execute-task [next pending N]`
+- All tasks complete, no paper → `/materio:wtfp`
+- All tasks complete, paper in progress → `/wtfp:progress`
+
+</process>

package/library/plugins/materio/ai.iowarp.clio/prompts/materio/upload-data.md

@@ -0,0 +1,104 @@
+---
+description: "Register and index data files, papers, or datasets for use in research tasks"
+argument-hint: "[file path or directory, optional]"
+---
+
+<clio_execution>
+Read ${component:resource:clio-execution} before acting. It defines argument parsing,
+research state helpers, interview ownership, readback, and optional recording.
+</clio_execution>
+
+<objective>
+Register data files (experimental results, papers, datasets, scripts) into the .research/data/ index so that task executors can find and use them. Does not move files; records paths and metadata.
+
+**Orchestrator role:** Accept file paths or scan for files, gather metadata via ask_user, write/update .research/DATA-INDEX.md.
+</objective>
+
+<context>
+Optional file path: $ARGUMENTS
+</context>
+
+<process>
+
+## 1. Find Files to Register
+
+If $ARGUMENTS provided:
+```bash
+[ -f "$ARGUMENTS" ] && echo "File exists: $ARGUMENTS"
+[ -d "$ARGUMENTS" ] && ls "$ARGUMENTS"
+```
+
+If no argument: scan for common data file types:
+```bash
+find . -name "*.csv" -o -name "*.xlsx" -o -name "*.txt" -o -name "*.pdf" \
+       -o -name "*.dat" -o -name "*.json" -o -name "*.mat" -o -name "*.bib" \
+       2>/dev/null | grep -v ".research" | grep -v ".claude" | grep -v ".git" | head -20
+```
+
+## 2. For Each File, Gather Metadata
+
+Use ask_user (batch for multiple files):
+- header: "Data Registration"
+- question: "Found these files:\n[list]\n\nFor each, tell me:\n1. **Type**: experimental-data | paper | dataset | script | model-output | other\n2. **Description**: What does it contain? (1 sentence)\n3. **Relevant tasks**: Which workflow tasks use this data?\n4. **Format notes**: Units, column headers, any preprocessing needed?"
+- options: "I'll describe them" | "Register all as-is with auto-detection"
+
+## 3. Copy to .research/data/ (optional)
+
+Use ask_user:
+- header: "Copy Files?"
+- question: "Copy files into .research/data/ for centralized storage, or just index their current locations?"
+- options: "Copy into .research/data/" | "Index in-place (keep original location)"
+
+If copy:
+```bash
+python3 "${component:script:research-state}" copy-data "$FILE"
+```
+
+## 4. Update DATA-INDEX.md
+
+Write or append to `.research/DATA-INDEX.md`:
+
+```markdown
+## [filename]
+- **Path**: [full path]
+- **Type**: [type]
+- **Description**: [description]
+- **Relevant tasks**: Task [N], Task [M]
+- **Format**: [format notes]
+- **Registered**: [date]
+```
+
+## 5. Record
+
+Only if `commit_research` is true in `.research/config.json`:
+```bash
+python3 "${component:script:research-state}" record --message "data: register [N] files; [brief description]" --files "${CHANGED_FILES[@]}"
+```
+
+</process>
+
+<offer_next>
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ Materio ► DATA REGISTERED ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Index: .research/DATA-INDEX.md
+Files: [N] registered
+
+───────────────────────────────────────────
+
+Data is now available to the literature reviewer and task executors.
+Papers and .bib files feed `/materio:literature-review`; datasets feed `/materio:execute-task [N]`.
+
+───────────────────────────────────────────
+
+</offer_next>
+
+<success_criteria>
+- [ ] All provided files located and verified
+- [ ] Type, description, and relevant tasks captured per file
+- [ ] DATA-INDEX.md written/updated
+- [ ] Files optionally copied to .research/data/
+- [ ] Committed only if commit_research is true
+</success_criteria>