swarmvault source

Manage recurring source roots through a registry-backed workflow.

Usage

swarmvault source add <input> [--review] [--guide] [--no-guide] [--answers-file <path>] [--no-compile] [--no-brief] [--max-pages <n>] [--max-depth <n>] [--branch <name>] [--ref <ref>] [--checkout-dir <path>]
swarmvault source list
swarmvault source reload [id] [--all] [--review] [--guide] [--no-guide] [--answers-file <path>] [--no-compile] [--no-brief] [--max-pages <n>] [--max-depth <n>]
swarmvault source review <id>
swarmvault source guide <id>
swarmvault source session <id> [--answers-file <path>]
swarmvault source delete <id>

Supported Inputs

• Local file paths
• Local directory paths
• Public GitHub repo root URLs such as https://github.com/karpathy/micrograd
• Docs/wiki/help/reference/tutorial hubs

For public GitHub repo roots, add --branch <name>, --ref <ref>, or --checkout-dir <path> when a recurring source needs a pinned branch, tag, commit, or reusable checkout directory.

Unsupported inputs fail fast and redirect you to the lower-level commands:

• use swarmvault ingest for direct local files or direct one-off URLs
• use swarmvault add for research/article normalization

What `source add` Does

By default, swarmvault source add:

1. Registers the source in state/sources.json
2. Syncs it into canonical vault storage
3. Runs one compile
4. Writes a source-scoped brief to wiki/outputs/source-briefs/<source-id>.md

Add --review to also stage a source review page under wiki/outputs/source-reviews/ and an approval bundle under state/approvals/. Add --guide when you want the stronger guided-session flow: source brief, a resumable session under wiki/outputs/source-sessions/, source review, source guide, and a clearly labeled guided approval bundle. Profiles using guidedSessionMode: "canonical_review" stage approval-queued canonical page edits; insights_only profiles keep exploratory synthesis in wiki/insights/. Set profile.guidedIngestDefault: true when that guided path should be the default for source add and source reload, and use --no-guide to force the lighter path on one run. --guide supersedes --review.

Managed-source working state lives under state/sources/<id>/.

Source-scoped artifacts are intentionally split by role:

Examples

swarmvault source add ./exports/customer-call.srt --guide
swarmvault source add ./apps/api
swarmvault source add https://github.com/karpathy/micrograd
swarmvault source add https://github.com/owner/repo --branch main --checkout-dir .swarmvault-checkouts/repo
swarmvault source add https://example.com/docs/getting-started --max-pages 8 --max-depth 2
swarmvault source list
swarmvault source session file-customer-call-srt-12345678
swarmvault source review file-customer-call-srt-12345678
swarmvault source reload --all
swarmvault source reload github-repo-karpathy-micrograd-12345678 --no-brief
swarmvault source delete github-repo-karpathy-micrograd-12345678

Notes

• Local directory sources remain compatible with watch --repo.
• Local file sources are useful for recurring transcripts, mailboxes, calendars, and other export files that should stay synced and reviewable.
• Remote GitHub and docs-crawl sources are manual source reload sources in this release.
• Git branch/ref/checkout options are only accepted for public GitHub repo root URLs.
• source delete removes registry and transient sync state only. It does not delete canonical raw/, wiki/, or saved output artifacts.
• Docs crawl stays same-domain and bounded. If the URL looks like a single article rather than a docs hub, use swarmvault add or swarmvault ingest instead.
• source review <id> accepts either a managed source id or a raw source id and stages a fresh source-scoped review artifact through the same approval queue used by compile --approve.
• source guide <id> remains a compatibility alias for the guided-session flow.
• source session <id> resumes the latest guided session for a managed source id, raw source id, source scope id, or session id.