scoutica scan

The scan command is the powerhouse of the Scoutica Protocol. It takes any directory of unstructured text, PDFs, or code and compresses it into a high-fidelity, machine-readable professional profile.

Caution

scan requires a configured AI provider in your PATH (for example, gemini, claude, or ollama). Before a remote-capable provider runs, Scoutica names the destination and discloses that it will receive the full generated prompt and document text. Interactive runs ask y/N; noninteractive runs must pass --allow-remote-provider. Ollama counts as local only when OLLAMA_HOST is unset/default or loopback. --clipboard makes no Scoutica network call, but places the same sensitive payload on your system clipboard for user-controlled transfer.

Command Syntax

scoutica scan <source-directory> [options]

Options

Option	Behavior
--clipboard	Skips executing the local AI CLI call. Instead, it aggressively copies the deeply formatted prompt and embedded documents directly into your system clipboard, allowing you to paste it into ChatGPT, Claude.ai, or Gemini Advanced.
--output <directory>	Selects the exact card directory before any provider call.
--with <provider>	Selects a fixed, characterized provider adapter.
--allow-remote-provider	Records consent for this invocation. Required for remote-capable providers in noninteractive use.
--force	Regenerates even when card-owned source state is unchanged.
<source>	Required. The directory containing your unstructured data (PDFs, Markdown, text, code, CVs).
[output]	Optional. The directory to write the generated JSON/YAML to. Defaults to ./.

---

The AI Parsing Pipeline

What it does: When you run scoutica scan ~/CV, the CLI engine initiates the following operations:

1. Reads supported top-level source documents with a 2 MiB extracted-text limit per file and 4 MiB aggregate limit. Over-limit input fails; it is never truncated.
2. Uses pdftotext to flatten any rich PDFs into rigorous raw plaintext.
3. Ingests supported top-level document formats (.md, .txt, JSON, YAML, CSV, HTML, PDF, and DOCX).
4. Wraps this context tightly inside a massive system prompt (pulled from your ~/.scoutica/templates/scoutica_prompt.txt).
5. Discloses the provider destination and obtains consent when it is remote-capable.
6. Supplies the payload through stdin or a request body, never as sensitive process arguments. Provider execution is capped at 300 seconds and the response at 8 MiB.
7. Parses and validates the complete generated card in private staging, then promotes it with rollback protection.
8. Writes source state only under <card>/.scoutica/state.json; unchanged scans can skip the provider without consulting legacy cwd state.

Why use it:

• Zero-effort adoption: Mapping 10 years of professional experience across 5 different companies into a JSON schema manually takes hours. scoutica scan accomplishes it in 15 seconds.
• Continuous Maintenance: You can run scan against a folder containing 3 new certifications, and it will automatically update your profile.

Use Case A: Zero-to-One

You have a folder called ~/professional/ containing resume.pdf, cover-letter.txt, and aws-cert.pdf.

scoutica scan ~/professional/ --output ./my-new-card/ --allow-remote-provider

The AI reads your Amazon certificate, places it under evidence.json, reads your PDF resume, structures it into profile.json, infers your location and remote preference into rules.yaml. You are completely done and ready to validate and publish.

Use Case B: The Clipboard Hack

You do not want to install any CLI dependencies, but you DO have an enterprise subscription to ChatGPT. You have a folder of complicated legal documents you wrote proving your legal history.

scoutica scan ~/legal-history/ --clipboard

Your clipboard now contains the master protocol system prompt + all the parsed text. You simply hit CMD+v inside ChatGPT, and it spits back exactly the structured files you need to copy into your repository.