# Thesa Autonomous Agent Guide
Use Thesa as the top-level router for ten bounded archive workflows. Choose one route from the target and evidence requested: `repoforge` for repositories, `modelforge` for models, `baseforge` for datasets, `siteforge` for websites, `assetforge` for free 3D assets, `cadforge` for STEP CAD files, `soundforge` for reusable audio, `paperforge` for scholarly papers and technical reports, or `videoforge` for exact public YouTube/X video URLs. The `thesa` route itself coordinates CLI/TUI selection, dry runs, progress, and `.thesa` integrity manifests.
Before execution, parse the target with the selected route, inspect provider-specific constraints, make a bounded plan, and prefer `--dry-run` when it can establish discovery and selection without downloads. Do not treat a dry run as proof that an existing archive is valid; skip-existing verification occurs during archival. Keep discovery, selection, output, concurrency, page, file, and byte limits explicit. Never remove, weaken, or bypass provider safety checks, URL allowlists, rights gates, archive caps, checksum verification, or path validation.
Credentials belong to the user. Request only credentials required by the chosen provider, prefer supported environment variables or secure local injection, never print token values or environment contents, and never persist credentials in archives, manifests, documentation, or commands reported back to the user. Anonymous routes must not invent a token step.
Obtain user approval before downloads, replacement, broad crawls, authenticated access, or other material side effects unless the user already explicitly approved the exact bounded operation. Present the provider, target, selection count, output path, limits, rights/attribution warnings, and replacement or skip behavior. An explicit empty interactive selection is a successful no-op.
VideoForge requires trusted local `yt-dlp`, `ffmpeg`, and `ffprobe` executables; current YouTube extraction may also require a supported JavaScript runtime and locally installed EJS components described by `yt-dlp`. Accept only one exact supported public YouTube or X/Twitter URL, inspect it before planning or archiving, keep the nonzero byte and timeout limits explicit, and obtain independent authorization through `--authorized`, legacy `--video-authorized`, or the exact interactive phrase `I AM AUTHORIZED`. Never infer authorization from a reported license or metadata. VideoForge and `yt-dlp` grant no download or content rights.
The video route accepts exact YouTube and X/Twitter status URLs. It does not support discovery lists, playlists, other providers, DRM content, authentication, cookies, credentials, proxies, geo bypass, access-control workarounds, arbitrary `yt-dlp` arguments, plugins, or remote components. Follow the provider terms, applicable law, and content-owner rights; retain the canonical source, attribution, reported license, redistribution warning, VideoForge manifest, and verified Thesa sidecar.
After execution, verify provider manifests and Thesa sidecars for every result claimed as archived or verified-skipped. Ensure selected, archived, skipped, and failed identities and counts agree before writing completion sidecars. Never overwrite an older sidecar for an item that failed. Report successful and skipped items first, then every partial failure with its bounded diagnostic; do not hide successful work because another item failed.
Routes:
- `thesa`: orchestration, route selection, top-level manifests, and verification.
- `repoforge` (`repos`, `repositories`): discover, clone, and safely refresh GitHub or Bitbucket repositories without overwriting dirty worktrees.
- `modelforge` (`models`): normalize and archive Hugging Face, Ollama, or CivitAI model targets with provider credentials and limits where needed.
- `baseforge` (`datasets`): discover and archive Hugging Face or Zenodo datasets; bound the selection externally because BaseForge does not impose total file or byte caps.
- `siteforge` (`sites`): capture bounded website crawls and produce raw evidence plus agent-readable indexes and representations.
- `assetforge` (`assets`, `3d`): discover rights-aware 3D bundles, retain attribution, and verify bounded provider files.
- `cadforge` (`cad`, `step`): discover STEP/STP/STEPZ links from supplied HTML pages and download them in bounded batches; review source terms and redistribution rights.
- `soundforge` (`audio`, `sounds`): archive allowlisted Wikimedia Commons originals while retaining exact license and attribution evidence.
- `paperforge` (`papers`, `paper`): discover and archive arXiv PDFs, Europe PMC JATS XML, or NASA NTRS PDFs while keeping metadata rights separate from document rights.
- `videoforge` (`videos`, `video`): inspect and archive one exact authorized public YouTube or X/Twitter URL with fixed quality, byte, timeout, and verification policy.
Use `thesa --agent` or `thesa --agent all` for every embedded guide. Use `thesa --agent thesa` for this guide, `thesa --agent videoforge` for the VideoForge guide, or select another Forge guide with any selector or alias shown above. Siteforge also provides `siteforge --agent`; the other Forge crates are libraries and expose their guide through `AGENT_GUIDE`. Unknown selectors are errors. Agent-guide output is stable plain Markdown and contains no runtime environment values.