@laitszkin/apollo-toolkit 2.7.0 → 2.9.0

package/scheduled-runtime-health-check/README.md

@@ -1,15 +1,16 @@
 # Scheduled Runtime Health Check
 
-An agent skill for scheduled, bounded project runs with post-run health analysis.
+An agent skill for running user-requested commands in a background terminal, optionally inside a bounded time window with post-run log analysis.
 
-This skill helps agents start a project at a chosen time, keep it alive for a fixed observation window, stop it automatically, collect the relevant logs, and summarize module health with evidence-backed findings from `analyse-app-logs`.
+This skill helps agents use a background terminal to run a requested command immediately or in a chosen time window, and optionally summarize evidence-backed findings from the resulting logs via `analyse-app-logs`.
 
 ## What this skill provides
 
-- A workflow for one-off or recurring runtime health checks.
+- A workflow for one-off or recurring background-terminal runtime checks.
+- An optional code-update step before execution.
 - Clear separation between scheduling, runtime observation, shutdown, and diagnosis.
 - A bounded log window so startup, steady-state, and shutdown evidence stay correlated.
-- Module-level health classification: `healthy`, `degraded`, `failed`, or `unknown`.
+- Optional module-level health classification: `healthy`, `degraded`, `failed`, or `unknown`.
 - Escalation to `improve-observability` when existing telemetry is insufficient.
 
 ## Repository structure
@@ -33,22 +34,28 @@ cp -R scheduled-runtime-health-check "$CODEX_HOME/skills/scheduled-runtime-healt
 Invoke the skill in your prompt:
 
 ```text
-Use $scheduled-runtime-health-check to start this project at 22:00, keep it running for 6 hours, stop it automatically, and analyze whether the API, worker, and scheduler modules stayed healthy.
+Use $scheduled-runtime-health-check to use a background terminal to run `docker compose up app worker`.
+
+Run it in this specific time window: 2026-03-18 22:00 to 2026-03-19 04:00 Asia/Hong_Kong.
+
+After the run completes, explain your findings from the logs.
 ```
 
 Best results come from including:
 
 - workspace path
-- start command
+- execution command
 - stop command or acceptable shutdown method
-- schedule and timezone
-- duration
+- schedule/time window and timezone
+- duration when bounded
 - readiness signal
 - relevant log files
-- modules or subsystems to assess
+- modules or subsystems to assess when findings are requested
+- whether the repository should be updated first, only if you want that behavior
 
 If no trustworthy start command is documented, the agent should derive it from the repository or ask only for that missing command.
 If the user requests a future start time and no reliable scheduler is available, the agent should report that limitation instead of starting the run early.
+If an optional update step was requested but the repository cannot be updated safely because the worktree is dirty or no upstream is configured, the agent should stop and report that exact blocker instead of forcing an update.
 
 ## Example
 
@@ -58,13 +65,14 @@ If the user requests a future start time and no reliable scheduler is available,
 Use $scheduled-runtime-health-check for this repository.
 
 Workspace: /workspace/my-app
-Start command: docker compose up app worker
+Execution command: docker compose up app worker
 Stop command: docker compose down
 Schedule: 2026-03-18 22:00 Asia/Hong_Kong
 Duration: 6 hours
 Readiness signal: GET http://127.0.0.1:3000/health returns 200
 Logs: docker compose logs, logs/app.log, logs/worker.log
 Modules to assess: api, worker, scheduler
+After completion: explain findings from the logs
 ```
 
 ### Expected response shape
@@ -73,21 +81,24 @@ Modules to assess: api, worker, scheduler
 1) Run summary
 - Started at 2026-03-18 22:00 HKT and stopped at 2026-03-19 04:00 HKT after a 6-hour bounded run.
 
-2) Module health
+2) Execution result
+- The background terminal completed the requested run workflow and kept the services up for the full window.
+
+3) Module health
 - api: healthy, served readiness checks and no error bursts were observed.
 - worker: degraded, repeated timeout warnings increased after 01:20 HKT.
 - scheduler: unknown, no positive execution signal was emitted during the window.
 
-3) Confirmed issues
+4) Confirmed issues
 - Reuse evidence-backed findings from $analyse-app-logs.
 
-4) Potential issues and validation needed
+5) Potential issues and validation needed
 - Scheduler may not be firing jobs; add a per-job execution log or metric to confirm.
 
-5) Observability gaps
+6) Observability gaps
 - Missing correlation IDs between api requests and worker jobs.
 
-6) Automation or scheduler status
+7) Automation or scheduler status
 - One bounded scheduled run completed and no further cleanup is required.
 ```
 

package/scheduled-runtime-health-check/SKILL.md

@@ -1,40 +1,51 @@
 ---
 name: scheduled-runtime-health-check
-description: Coordinate a scheduled, bounded project run that starts automatically, stays up for a fixed observation window, stops cleanly, and delegates log-based health analysis to analyse-app-logs. Use when users want timed project startups, post-run health checks across modules, and a report of confirmed issues and potential risks.
+description: Use a background terminal to run a user-specified command immediately or in a requested time window, and optionally explain findings from the captured logs after the run. Use when users want timed project execution, bounded runtime checks, or post-run log-based findings.
 ---
 
 # Scheduled Runtime Health Check
 
 ## Dependencies
 
-- Required: `analyse-app-logs` for bounded post-run log analysis.
+- Required: `analyse-app-logs` when the user asks for post-run log findings or when the observed run needs evidence-backed diagnosis.
 - Conditional: `improve-observability` when current logs cannot prove module health or root cause.
 - Optional: `open-github-issue` indirectly through `analyse-app-logs` when confirmed issues should be published.
 - Fallback: If no scheduler or automation capability is available for the requested future start time, stop and report that scheduling could not be created; only run immediately when the user explicitly allows an immediate bounded observation instead of a timed start.
 
 ## Standards
 
-- Evidence: Anchor every conclusion to the scheduled window, startup/shutdown timestamps, captured logs, and concrete module signals.
-- Execution: Collect the run contract, choose a scheduling mechanism, capture logs, run for a bounded window, stop cleanly, then delegate the review to `analyse-app-logs`.
-- Quality: Keep scheduling and shutdown deterministic, separate confirmed findings from hypotheses, and mark each module healthy/degraded/failed/unknown with reasons.
-- Output: Return the run configuration, module health by area, confirmed issues, potential issues, observability gaps, and automation or scheduler status.
+- Evidence: Anchor every conclusion to the requested command, execution window, startup/shutdown timestamps, captured logs, and concrete runtime signals.
+- Execution: Collect the run contract, use a background terminal, optionally update the code only when the user asks, execute the requested command immediately or in the requested window, capture logs, stop cleanly when bounded, then delegate log review to `analyse-app-logs` only when findings are requested or needed.
+- Quality: Keep scheduling, execution, and shutdown deterministic; separate confirmed findings from hypotheses; and mark each assessed module healthy/degraded/failed/unknown with reasons.
+- Output: Return the run configuration, execution status, log locations, optional code-update result, optional module health by area, confirmed issues, potential issues, observability gaps, and scheduler status when applicable.
 
 ## Overview
 
-Use this skill when the user wants an agent to:
+Use this skill when the user wants an agent to do work in this shape:
 
-- start a project at a specific time
-- keep it running for a fixed window such as 6 hours
-- stop it automatically at the end of that window
-- collect logs from startup through shutdown
-- assess whether key modules behaved normally
-- identify confirmed problems and potential risks from the observed run
+- use a background terminal for the whole run
+- execute a specific command such as `npm run dev`, `docker compose up`, or another repo-defined entrypoint
+- optionally update the project before execution when the user explicitly asks
+- optionally run it inside a specific time window
+- optionally wait for the run to finish and then explain findings from the logs
 
-This skill is an orchestration layer. It owns the schedule, bounded runtime, log capture, and module-level health summary. It delegates deep log diagnosis to `analyse-app-logs`.
+Canonical task shape:
+
+`Use $scheduled-runtime-health-check to use a background terminal to run <command>.`
+
+Optional suffixes:
+
+- `Before running, update this project to the latest safe code state.`
+- `Run it in this specific time window: <window>.`
+- `After the run completes, explain your findings from the logs.`
+
+This skill is an orchestration layer. It owns the background terminal session, optional code-update step, optional scheduling, bounded runtime, log capture, and optional module-level health summary. It delegates deep log diagnosis to `analyse-app-logs` only when the user asks for findings or the run clearly needs evidence-backed analysis.
 
 ## Core principles
 
 - Prefer one bounded observation window over open-ended monitoring.
+- Use one dedicated background terminal session per requested run so execution and logs stay correlated.
+- Treat code update as optional and only perform it when the user explicitly requests it.
 - Treat startup, steady-state, and shutdown as part of the same investigation.
 - Do not call a module healthy unless there is at least one positive signal for it.
 - Separate scheduler failures, boot failures, runtime failures, and shutdown failures.
@@ -43,44 +54,45 @@ This skill is an orchestration layer. It owns the schedule, bounded runtime, log
 ## Required workflow
 
 1. Define the run contract
-   - Confirm or derive the workspace, start command, stop method, schedule, duration, readiness signal, log locations, and modules to assess.
+   - Confirm or derive the workspace, execution command, optional code-update step, optional schedule, optional duration, readiness signal, log locations, and whether post-run findings are required.
    - Derive commands from trustworthy sources first: `package.json`, `Makefile`, `docker-compose.yml`, `Procfile`, scripts, or project docs.
-   - If no trustworthy start command or stop method can be found, stop and ask only for the missing command rather than guessing.
-2. Choose the scheduling mechanism
-   - Prefer the host's native automation or scheduled-task system when available.
-   - Prefer a single scheduled execution that performs start -> observe -> stop -> analyze so the log window is exact.
-   - If the platform cannot hold a long-running scheduled task, use paired start/stop jobs and record both task identifiers.
+   - If no trustworthy execution command or stop method can be found, stop and ask only for the missing command rather than guessing.
+2. Prepare the background terminal run
+   - Use a dedicated background terminal session for the whole workflow.
+   - Create a dedicated run folder and record timezone, cwd, requested command, terminal session identifier, and any requested start/end boundaries.
+   - Capture stdout and stderr from the beginning of the session so the full run stays auditable.
+3. Optionally update to the latest safe code state
+   - Only do this step when the user explicitly asked to update the project before execution.
+   - Prefer the repository's normal safe update path, such as `git pull --ff-only`, or the project's documented sync command if one exists.
+   - Record the commit before and after the update.
+   - If the worktree is dirty, the branch has no upstream, or the update cannot be done safely, stop and report the exact blocker instead of guessing or forcing a merge.
+4. Choose the execution timing
+   - If the user gave a specific time window, schedule or delay the same background-terminal run to start in that window.
+   - If no time window was requested, run immediately after setup, or after the optional update step if one was requested.
    - If the user requested a future start time and no reliable scheduler is available, fail closed and report the scheduling limitation instead of starting early.
-3. Prepare bounded log capture
-   - Create a dedicated run folder for the window and record absolute start time, intended end time, timezone, cwd, command, and PID or job identifier.
-   - Capture stdout and stderr for the started process, plus any existing app log files that matter for diagnosis.
-   - Keep startup, runtime, and shutdown evidence in the same run record.
-4. Start and verify readiness
-   - Launch the project at the scheduled time.
-   - Wait for a concrete readiness signal such as a health endpoint, listening-port log, worker boot line, or queue-consumer ready message.
-   - If readiness never arrives, stop the run, preserve logs, and analyze the failed startup window.
-5. Observe during the bounded window
-   - Track crashes, restarts, retry storms, timeout bursts, stuck jobs, resource pressure, and repeated warnings.
-   - For each requested module or subsystem, gather at least one positive signal and any degradation signal in the same window.
-   - If the user did not list modules explicitly, infer the major runtime modules from the repository structure and runtime processes.
-6. Stop cleanly at the end of the window
-   - Use the project's normal shutdown path first.
-   - If graceful stop fails, escalate deterministically and record the exact stop sequence and timestamps.
-   - Treat abnormal shutdown behavior as a health signal, not just an operational detail.
-7. Delegate bounded log analysis
+5. Run and capture readiness
+   - Execute the requested command in the same background terminal.
+   - Wait for a concrete readiness signal when the command is expected to stay up, such as a health endpoint, listening-port log, worker boot line, or queue-consumer ready message.
+   - If readiness never arrives, stop the run, preserve logs, and treat it as a failed startup window.
+6. Observe and stop when bounded
+   - If a bounded window or explicit stop time was requested, keep the process running only for that agreed window and then stop it cleanly.
+   - Track crashes, restarts, retry storms, timeout bursts, stuck jobs, resource pressure, and repeated warnings during the run.
+   - Use the project's normal shutdown path first; if graceful stop fails, escalate deterministically and record the exact stop sequence and timestamps.
+7. Explain findings from logs when requested
+   - If the user asked for findings after completion, wait for the run to finish before analyzing the captured logs.
    - Invoke `analyse-app-logs` on only the captured runtime window.
    - Pass the service or module names, environment, timezone, run folder, relevant log files, and the exact start/end boundaries.
    - Reuse its confirmed issues, hypotheses, and monitoring improvements instead of rewriting a separate incident workflow.
-8. Produce the runtime health report
-   - Summarize the schedule that was executed, whether readiness succeeded, how long the project stayed healthy, and how shutdown behaved.
-   - Classify each module as `healthy`, `degraded`, `failed`, or `unknown` with concrete evidence.
-   - Separate already observed issues from potential risks that need more telemetry or a longer run to confirm.
+8. Produce the final report
+   - Always summarize the actual command executed, actual start/end timestamps, execution status, and log locations.
+   - Include the code-update result only when an update step was requested.
+   - When findings were requested, classify each relevant module as `healthy`, `degraded`, `failed`, or `unknown` with concrete evidence and separate observed issues from risks that still need validation.
 
 ## Scheduling rules
 
 - Use the user's locale timezone when configuring scheduled tasks.
 - Name scheduled jobs clearly so the user can recognize start, stop, and analysis ownership.
-- Prefer recurring schedules only when the user explicitly wants repeated health checks; otherwise create a one-off bounded run.
+- Prefer recurring schedules only when the user explicitly wants repeated checks; otherwise create a one-off bounded run.
 - If the host provides agent automations, use them before inventing project-local scheduling files.
 - If native automation is unavailable, prefer the smallest reliable OS-level scheduling method already present on the machine.
 - If the request depends on a future start time and no reliable scheduling method exists, do not silently convert the request into an immediate run.
@@ -99,21 +111,26 @@ Absence of errors alone is not enough for `healthy`.
 Use this structure in responses:
 
 1. Run summary
-   - Workspace, schedule, actual start/end timestamps, duration, readiness result, shutdown result, and log locations.
-2. Module health
-   - One entry per module with status (`healthy` / `degraded` / `failed` / `unknown`) and evidence.
-3. Confirmed issues
-   - Reuse evidence-backed findings from `analyse-app-logs`.
-4. Potential issues and validation needed
-   - Risks that appeared in the run but need more evidence.
-5. Observability gaps
-   - Missing logs, metrics, probes, or correlation IDs that blocked diagnosis.
-6. Automation or scheduler status
-   - Created task identifiers, execution status, and whether future cleanup is needed.
+   - Workspace, command, schedule if any, actual start/end timestamps, duration if bounded, readiness result, shutdown result if applicable, and log locations.
+2. Execution result
+   - Whether the command completed, stayed up for the requested window, or failed early.
+3. Code update result
+   - Include only when an update step was requested. Record the update command, before/after commit, or the exact blocker.
+4. Module health
+   - Include only when findings were requested or health assessment was part of the task. One entry per module with status (`healthy` / `degraded` / `failed` / `unknown`) and evidence.
+5. Confirmed issues
+   - Include only when log analysis was requested. Reuse evidence-backed findings from `analyse-app-logs`.
+6. Potential issues and validation needed
+   - Include only when log analysis was requested. Risks that appeared in the run but need more evidence.
+7. Observability gaps
+   - Include only when log analysis was requested. Missing logs, metrics, probes, or correlation IDs that blocked diagnosis.
+8. Automation or scheduler status
+   - Include only when a future window or scheduler was involved. Record task identifiers, execution status, and whether future cleanup is needed.
 
 ## Guardrails
 
 - Do not let the project continue running past the agreed window unless the user explicitly asks.
+- Do not perform a code-update step unless the user explicitly asked for it.
 - Do not claim steady-state health from startup-only evidence.
 - Keep the run folder and scheduler metadata so the investigation can be reproduced.
 - If current logs are too weak to judge module health, recommend `improve-observability` instead of stretching the evidence.

package/scheduled-runtime-health-check/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Scheduled Runtime Health Check"
-  short_description: "Schedule a bounded project run, then assess module health from captured logs."
-  default_prompt: "Use $scheduled-runtime-health-check to schedule a bounded project run, capture logs from startup through shutdown, classify module health across the requested subsystems, and delegate evidence-based post-run diagnosis to $analyse-app-logs."
+  short_description: "Use a background terminal to run a command in a time window and optionally explain findings from logs."
+  default_prompt: "Use $scheduled-runtime-health-check to use a background terminal to run the requested command immediately or in the requested time window, optionally update the project first only when the user asks for that, capture logs through the run, and, when findings are requested, delegate bounded post-run log diagnosis to $analyse-app-logs."

package/scripts/install_skills.ps1

@@ -12,9 +12,9 @@ Usage:
   ./scripts/install_skills.ps1 [codex|openclaw|trae|all]...
 
 Modes:
-  codex     Install links into ~/.codex/skills
-  openclaw  Install links into ~/.openclaw/workspace*/skills
-  trae      Install links into ~/.trae/skills
+  codex     Copy skills into ~/.codex/skills
+  openclaw  Copy skills into ~/.openclaw/workspace*/skills
+  trae      Copy skills into ~/.trae/skills
   all       Install all supported targets
 
 Optional environment overrides:
@@ -33,7 +33,7 @@ function Show-Banner {
   @"
 +------------------------------------------+
 |              Apollo Toolkit              |
-|      npm installer and skill linker      |
+|      npm installer and skill copier      |
 +------------------------------------------+
 "@
 }
@@ -180,7 +180,7 @@ function Remove-PathForce {
   }
 }
 
-function Link-Skill {
+function Copy-Skill {
   param(
     [string]$Source,
     [string]$TargetRoot
@@ -192,15 +192,8 @@ function Link-Skill {
   New-Item -ItemType Directory -Path $TargetRoot -Force | Out-Null
   Remove-PathForce -Target $target
 
-  try {
-    New-Item -Path $target -ItemType SymbolicLink -Target $Source -Force | Out-Null
-    Write-Host "[linked] $target -> $Source"
-  }
-  catch {
-    # Fallback for environments where symlink permission is restricted.
-    New-Item -Path $target -ItemType Junction -Target $Source -Force | Out-Null
-    Write-Host "[linked-junction] $target -> $Source"
-  }
+  Copy-Item -LiteralPath $Source -Destination $target -Recurse -Force
+  Write-Host "[copied] $Source -> $target"
 }
 
 function Install-Codex {
@@ -215,7 +208,7 @@ function Install-Codex {
 
   Write-Host "Installing to codex: $target"
   foreach ($src in $SkillPaths) {
-    Link-Skill -Source $src -TargetRoot $target
+    Copy-Skill -Source $src -TargetRoot $target
   }
 }
 
@@ -242,7 +235,7 @@ function Install-OpenClaw {
     $skillsDir = Join-Path $workspace.FullName "skills"
     Write-Host "Installing to openclaw workspace: $skillsDir"
     foreach ($src in $SkillPaths) {
-      Link-Skill -Source $src -TargetRoot $skillsDir
+      Copy-Skill -Source $src -TargetRoot $skillsDir
     }
   }
 }
@@ -259,7 +252,7 @@ function Install-Trae {
 
   Write-Host "Installing to trae: $target"
   foreach ($src in $SkillPaths) {
-    Link-Skill -Source $src -TargetRoot $target
+    Copy-Skill -Source $src -TargetRoot $target
   }
 }
 

package/scripts/install_skills.sh

@@ -7,9 +7,9 @@ Usage:
   ./scripts/install_skills.sh [codex|openclaw|trae|all]...
 
 Modes:
-  codex     Install symlinks into ~/.codex/skills
-  openclaw  Install symlinks into ~/.openclaw/workspace*/skills
-  trae      Install symlinks into ~/.trae/skills
+  codex     Copy skills into ~/.codex/skills
+  openclaw  Copy skills into ~/.openclaw/workspace*/skills
+  trae      Copy skills into ~/.trae/skills
   all       Install all supported targets
 
 Optional environment overrides:
@@ -29,7 +29,7 @@ show_banner() {
   cat <<'BANNER'
 +------------------------------------------+
 |              Apollo Toolkit              |
-|      npm installer and skill linker      |
+|      npm installer and skill copier      |
 +------------------------------------------+
 BANNER
 }
@@ -74,7 +74,7 @@ collect_skills() {
   fi
 }
 
-replace_with_symlink() {
+replace_with_copy() {
   local src="$1"
   local target_root="$2"
   local name target
@@ -86,8 +86,8 @@ replace_with_symlink() {
   if [[ -e "$target" || -L "$target" ]]; then
     rm -rf "$target"
   fi
-  ln -s "$src" "$target"
-  echo "[linked] $target -> $src"
+  cp -R "$src" "$target"
+  echo "[copied] $src -> $target"
 }
 
 install_codex() {
@@ -96,7 +96,7 @@ install_codex() {
 
   echo "Installing to codex: $codex_skills_dir"
   for src in "${SKILL_PATHS[@]}"; do
-    replace_with_symlink "$src" "$codex_skills_dir"
+    replace_with_copy "$src" "$codex_skills_dir"
   done
 }
 
@@ -120,7 +120,7 @@ install_openclaw() {
     skills_dir="$workspace/skills"
     echo "Installing to openclaw workspace: $skills_dir"
     for src in "${SKILL_PATHS[@]}"; do
-      replace_with_symlink "$src" "$skills_dir"
+      replace_with_copy "$src" "$skills_dir"
     done
   done
 }
@@ -131,7 +131,7 @@ install_trae() {
 
   echo "Installing to trae: $trae_skills_dir"
   for src in "${SKILL_PATHS[@]}"; do
-    replace_with_symlink "$src" "$trae_skills_dir"
+    replace_with_copy "$src" "$trae_skills_dir"
   done
 }
 

package/shadow-api-model-research/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: shadow-api-model-research
+description: Investigate gated or shadow LLM APIs by capturing real client request shapes, separating request-shape gating from auth/entitlement checks, replaying verified traffic patterns, and attributing the likely underlying model with black-box fingerprinting. Use when users ask how Codex/OpenClaw/custom-provider traffic works, want a capture proxy or replay harness, need LLMMAP-style model comparison, or want a research report on which model a restricted endpoint likely wraps.
+---
+
+# Shadow API Model Research
+
+## Dependencies
+
+- Required: `answering-questions-with-research` for primary-source web verification and code-backed explanations.
+- Conditional: `openclaw-configuration` when the capture path uses OpenClaw custom providers or workspace config edits; `deep-research-topics` when the user wants a formal report, especially PDF output.
+- Optional: none.
+- Fallback: If you cannot inspect either the real client code path or authorized live traffic, stop and report the missing evidence instead of guessing from headers or marketing copy.
+
+## Standards
+
+- Evidence: Base conclusions on actual client code, captured traffic, official docs, and controlled replay results; do not infer protocol details from memory alone.
+- Execution: Split the job into request-shape capture, replay validation, and model-attribution analysis; treat each as a separate hypothesis gate.
+- Quality: Distinguish request-shape compatibility, auth or entitlement requirements, system-prompt wrapping, and underlying-model behavior; never collapse them into one claim.
+- Output: Return the tested providers, exact capture or replay setup, prompt set or scoring rubric, observed differences, and an explicit confidence statement plus caveats.
+
+## Goal
+
+Help another agent run lawful, evidence-based shadow-API research without drifting into guesswork about what a gated endpoint checks or which model it wraps.
+
+## Workflow
+
+### 1. Classify the research ask
+
+Decide which of these the user actually needs:
+
+- capture the true request shape from a known client
+- configure OpenClaw or another client to hit a controlled endpoint
+- build a replay harness from observed traffic
+- compare the endpoint against known providers with black-box prompts
+- package findings into a concise report
+
+If the user is mixing all of them, still execute in that order: capture first, replay second, attribution third.
+
+### 2. Verify the real client path before writing any script
+
+- Inspect the local client code and active config first.
+- For OpenClaw, load the relevant official docs or local source through `answering-questions-with-research`, and use `openclaw-configuration` if you need to rewire a custom provider for capture.
+- When Codex or another official client is involved, verify current behavior from primary sources and the local installed code when available.
+- Do not claim that a request shape is "Codex-compatible" or "OpenClaw-compatible" until you have either:
+  - captured it from the client, or
+  - confirmed it from the current implementation and docs.
+
+### 3. Capture the true request shape
+
+- Read `references/request-shape-checklist.md` before touching the network path.
+- Prefer routing the real client to a capture proxy or controlled upstream you own.
+- Record, at minimum:
+  - method
+  - path
+  - query parameters
+  - headers
+  - body schema
+  - streaming or SSE frame shape
+  - retries, timeouts, and backoff behavior
+  - any client-added metadata that changes between providers or models
+- Treat aborted turns or partially applied config edits as tainted state; re-check the active config before trusting a capture.
+
+### 4. Separate request gating from auth or entitlement
+
+- Build explicit hypotheses for what the endpoint may be checking:
+  - plain OpenAI-compatible schema only
+  - static headers or user-agent shape
+  - transport details such as SSE formatting
+  - token claims, workspace identity, or other entitlement state
+- Do not tell the user that replaying the request shape is sufficient unless the replay actually works.
+- If the evidence shows the endpoint still rejects cloned traffic, report that the barrier is likely beyond the visible request shape.
+
+### 5. Build the replay harness only from observed facts
+
+- Read `references/fingerprinting-playbook.md` before implementing the replay phase.
+- Use `.env` or equivalent env-backed config for base URLs, API keys, and provider labels.
+- Mirror only the fields that were actually observed from the client.
+- Keep capture and replay scripts separate unless there is a strong reason to combine them.
+- Preserve the observed stream mode; do not silently downgrade SSE to non-streaming or vice versa.
+
+### 6. Run black-box fingerprinting
+
+- Compare the target endpoint against one or more control providers with known or documented models.
+- Use a prompt matrix that spans:
+  - coding or tool-use style
+  - factual knowledge questions with externally verified answers
+  - refusal and policy behavior
+  - instruction-following edge cases
+  - long-context or truncation behavior when relevant
+- When building factual question sets, verify the answer key from primary sources or fresh web research instead of relying on memory.
+- If the user wants LLMMAP-style comparison, keep the benchmark inputs fixed across providers and score each response on the same rubric.
+
+### 7. Report with confidence and caveats
+
+- Summarize:
+  - what was captured
+  - what replayed successfully
+  - which differences were protocol-level versus model-level
+  - the most likely underlying model family
+  - the confidence level and why
+- If system prompts or provider-side wrappers likely distort the output, say so explicitly and lower confidence accordingly.
+- If the user wants a report artifact, hand off to `deep-research-topics` after the evidence has been collected.
+
+## References
+
+- `references/request-shape-checklist.md` for the capture and replay evidence checklist.
+- `references/fingerprinting-playbook.md` for comparison design, scoring dimensions, and report structure.
+
+## Guardrails
+
+- Keep the work on systems the user is authorized to inspect or test.
+- Do not present speculation about hidden auth checks as established fact.
+- Do not over-index on one response; model attribution needs repeated prompts and multiple signal types.

package/shadow-api-model-research/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Shadow API Model Research"
+  short_description: "Capture gated client traffic and attribute likely model families"
+  default_prompt: "Use $shadow-api-model-research when the task is to inspect Codex/OpenClaw/custom-provider request shapes, build a capture or replay workflow, compare a restricted endpoint against control providers, or estimate the likely underlying model with black-box fingerprinting."

package/shadow-api-model-research/references/fingerprinting-playbook.md

@@ -0,0 +1,69 @@
+# Fingerprinting Playbook
+
+Use this playbook after you have trustworthy captured traffic or a validated replay harness.
+
+## Comparison design
+
+- Keep prompts, temperature-like settings, and stream mode fixed across providers.
+- Prefer at least one documented control provider with a known model family.
+- Run multiple prompt categories; one category is not enough for attribution.
+
+## Recommended prompt categories
+
+### 1. Factual knowledge
+
+- Use questions with fresh, externally verifiable answers.
+- Build the answer key from current primary sources or credible web verification.
+- Score for correctness, completeness, and unsupported claims.
+
+### 2. Coding style
+
+- Use short implementation tasks and bug-fix prompts.
+- Compare code structure, caution level, and explanation style.
+
+### 3. Instruction following
+
+- Use prompts with explicit formatting or ranking constraints.
+- Compare compliance, stability, and unnecessary extra content.
+
+### 4. Refusal and policy behavior
+
+- Use borderline prompts that should trigger a recognizable refusal or safe alternative.
+- Compare refusal style, redirect wording, and partial compliance behavior.
+
+### 5. Long-context behavior
+
+- Only run this when the target is expected to support larger contexts.
+- Compare truncation, summarization drift, and consistency across later references.
+
+## Scoring dimensions
+
+Score each response on a fixed rubric, for example:
+
+- factual accuracy
+- completeness
+- instruction compliance
+- reasoning clarity
+- code quality
+- refusal consistency
+- verbosity control
+- latency or throughput when that matters
+
+Use the same rubric for every provider and every prompt.
+
+## Confidence discipline
+
+- High confidence needs multiple converging signals across categories.
+- Medium confidence fits cases where the target tracks one family strongly but wrappers may distort style.
+- Low confidence fits cases where the protocol was captured but output signals remain mixed.
+
+## Suggested report structure
+
+1. Research objective
+2. Capture setup
+3. Replay validation status
+4. Prompt matrix and controls
+5. Scoring rubric
+6. Comparative findings
+7. Most likely model family
+8. Caveats, including wrappers and system prompts