Skip to content

README.md

Latest commit

 

History

History
76 lines (52 loc) · 4.52 KB

README.md

File metadata and controls

76 lines (52 loc) · 4.52 KB
Raw

Spotlight — Documentation

Spotlight is a runtime-agnostic OSINT investigation system with 17 skills, 2 agents, 8 schemas, and investigation-scoped monitoring orchestration. Point your agent runtime (pi, Hermes, Goose, Codex, Gemini, or any OpenAI-compatible harness) at this repo and run full-fidelity investigations end-to-end.

This docs/ directory is the operator manual. AGENTS.md at the repo root is the machine-readable contract your runtime loads at startup.

Reading order

If you are new to Spotlight, read in this order:

  1. structure.md — how this repo is laid out; what each file is for; the 13-verb contract
  2. runtimes.md — how to wire Spotlight into pi, Hermes, Goose, Codex, Gemini, or a local OpenAI-compatible fine-tune
  3. integrations.md — external OSINT tool integrations (dev-browser, Junkipedia, Noosphere C2PA, OSINT Navigator, Scoutpost, Unpaywall), manifest contract, preflight
  4. investigating.md — the investigation pipeline: brief, methodology, cycles, gates, readiness, stall protocol
  5. technical-investigation.md — CTI-derived methods, tier loading, case contracts, verified export, source review, and update policy
  6. fact-checking.md — the independent verification pass: SIFT, verdict taxonomy, evidence trails
  7. epistemic-grounding.md — claim-to-evidence grounding, evidence bundles, confidence caps
  8. vulnerabilities.md — shell-safety vulnerabilities and v2 mitigations
  9. sensitivity.md — design doc (not yet implemented): protecting sensitive material via physical separation, escalation, and one-way declassification
  10. monitoring.md — monitoring orchestration across Mycroft, Scoutpost, and runtime-native fallbacks
  11. recovery.md — when things break: agent crashes, corrupted files, stale locks, API failures

60-second quick-start

pi (MIT TypeScript harness — https://pi.dev)

pi natively reads AGENTS.md + skills/*/SKILL.md. Drop this repo at ~/.pi/agent/ (or symlink it), launch pi, and the skills load automatically.

ln -s /Users/you/buried_signals/spotlight ~/.pi/agent/spotlight
pi
# > Start a Spotlight investigation on {lead}.

Configure a local fine-tune provider in pi's models.json to route inference to your own OpenAI-compatible endpoint (llama-server, Ollama, Exoscale, vLLM) — see runtimes.md.

Hermes (Mac Mini ambient agent)

Edit ~/.hermes/config.yaml:

skills:
  external_dirs:
    - /Users/you/buried_signals/spotlight/skills

Restart Hermes. The orchestrator is invocable via invoke-skill("spotlight"). Sensitive work routes to local-gemma (llama-server on 127.0.0.1:8081).

Goose (extension pack)

Package this repo as a Goose extension. See runtimes.md for the extension manifest and recipe entry point.

Codex CLI / Gemini CLI

Both read AGENTS.md natively. Point them at the repo root as the project context. Verb bindings mirror pi's.

Claude Code note

The existing buriedsignals/[email protected] marketplace plugin at ~/buried_signals/tools/skills/spotlight/ is the Claude Code path. It is not served from this repo — the agnostic repo exists precisely so non-Claude runtimes have the same capability without a Claude plugin dependency.

The invariants (what never changes across runtimes)

Every runtime must preserve these — they are the editorial contract:

  • Pipeline: Preflight → Brief → Methodology → Execution → Gate 1 → Ingestion
  • Cycle limit 5, stall protocol on N ≥ 5 without readiness
  • Six readiness criteria (findings, independence, disputes, affected perspective, document trail, gap assessment)
  • Investigator modes: PLANNING and EXECUTION
  • Fact-checker: SIFT methodology, verdicts verified | unverified | disputed | false, independent spawn
  • Evidence grounding: scrape-before-cite, local_file on every source, archive before cite
  • Epistemic grounding: every claim records why the evidence supports, partially supports, contradicts, or fails to support it
  • Shell safety: untrusted values are validated before shell execution; destructive operations require probes
  • access_method enum and its confidence caps
  • Archive hierarchy: Wayback → Archive.today → local

These live in AGENTS.md, skills/spotlight/SKILL.md, and the agent prompts. See investigating.md for the details.