snipara-companion 1.3.7 → 1.3.8

package/README.md

@@ -472,6 +472,8 @@ snipara-companion upload --path docs/spec.md --file ./docs/spec.md
 snipara-companion upload --path clients/acme/current.md --file ./current.md --asset-class BUSINESS_DOCUMENT --usage-mode current_truth --source-kind local_agent --client-id acme
 snipara-companion upload --path diagrams/network.vsdx --file ./diagrams/network.vsdx --kind BINARY --format vsdx --reindex
 snipara-companion upload --path docs/spec.md --file ./docs/spec.md --reindex
+snipara-companion references scan --allow-domain docs.stripe.com --allow-domain docs.github.com
+snipara-companion references ingest --upload --reindex
 snipara-companion business-collections list
 snipara-companion business-collections ensure --preset business_response_playbook
 snipara-companion business-collections ensure --preset offer_templates
@@ -565,6 +567,29 @@ snipara-companion task-commit --summary "Validated PR Answer Pack release docs"
 Only add a dedicated `snipara-companion github answer-packs` command if Snipara
 ships a public API for manual regeneration or inspection outside the dashboard.
 
+### External References
+
+Use `references` when repository docs point at source material the agent may not
+be able to fetch directly, such as SDK docs, vendor runbooks, RFCs, or client
+pages:
+
+```bash
+snipara-companion references scan \
+  --allow-domain docs.stripe.com \
+  --allow-domain docs.github.com
+
+snipara-companion references ingest --dry-run
+snipara-companion references ingest --upload --reindex
+```
+
+`scan` writes `.snipara/references/manifest.json` with each URL, source file,
+line number, domain, and allowlist status. URLs are only ingested when their
+domain is allowlisted in the manifest or passed with `--allow-domain` at ingest
+time. `ingest` fetches allowed URLs into local Markdown snapshots under
+`.snipara/references/snapshots/`; `--upload` sends those snapshots to Snipara as
+external reference documents with source URL, content hash, fetch time, HTTP
+metadata, and referenced-from provenance.
+
 ### Project Intelligence Briefs
 
 Use `intelligence brief` when a task needs one local entrypoint for continuity,

package/dist/index.d.ts

@@ -1640,6 +1640,91 @@ declare function buildAgenticTimeline(options?: {
     cwd?: string;
 }): AgenticTimeline;
 
+declare const MANIFEST_VERSION = "snipara.references.v1";
+type ReferenceStatus = "allowed" | "pending" | "denied" | "unsupported";
+interface ReferenceOccurrence {
+    file: string;
+    line: number;
+    label?: string;
+}
+interface ReferenceManifestItem {
+    id: string;
+    url: string;
+    normalizedUrl: string;
+    domain: string;
+    status: ReferenceStatus;
+    reason: string;
+    discoveredAt: string;
+    occurrences: ReferenceOccurrence[];
+    latestSnapshotPath?: string;
+    latestFetchStatus?: number;
+    latestFetchAt?: string;
+    latestContentHash?: string;
+    latestError?: string;
+}
+interface ReferenceManifest {
+    version: typeof MANIFEST_VERSION;
+    generatedAt: string;
+    root: string;
+    allowDomains: string[];
+    denyDomains: string[];
+    items: ReferenceManifestItem[];
+}
+interface ScanReferencesOptions {
+    root?: string;
+    output?: string;
+    allowDomain?: string[];
+    denyDomain?: string[];
+    extensions?: string[];
+    maxFiles?: number;
+    json?: boolean;
+}
+interface IngestReferencesOptions {
+    manifest?: string;
+    outputDir?: string;
+    allowDomain?: string[];
+    ids?: string[];
+    max?: number;
+    timeoutMs?: number;
+    maxBytes?: number;
+    destinationPrefix?: string;
+    upload?: boolean;
+    reindex?: boolean;
+    dryRun?: boolean;
+    json?: boolean;
+}
+interface ScanSummary {
+    manifest: ReferenceManifest;
+    outputPath: string;
+    scannedFiles: number;
+    foundUrls: number;
+    allowed: number;
+    pending: number;
+    denied: number;
+    unsupported: number;
+}
+interface IngestSummary {
+    manifestPath: string;
+    selected: number;
+    fetched: number;
+    uploaded: number;
+    failed: number;
+    dryRun: boolean;
+    snapshots: Array<{
+        id: string;
+        url: string;
+        snapshotPath?: string;
+        destinationPath?: string;
+        status?: number;
+        uploaded?: boolean;
+        error?: string;
+    }>;
+}
+declare function scanReferences(options?: ScanReferencesOptions): ScanSummary;
+declare function ingestReferences(options?: IngestReferencesOptions): Promise<IngestSummary>;
+declare function referencesScanCommand(options: ScanReferencesOptions): Promise<void>;
+declare function referencesIngestCommand(options: IngestReferencesOptions): Promise<void>;
+
 type CacheStrategy = "exact" | "nearby" | "warm";
 interface QueryCacheScope {
     cwd?: string;
@@ -2062,4 +2147,4 @@ interface WrittenOrchestratorHandoff {
 declare function buildOrchestratorHandoff(options: OrchestratorHandoffOptions): OrchestratorHandoffArtifact;
 declare function writeOrchestratorHandoff(options: OrchestratorHandoffOptions): WrittenOrchestratorHandoff;
 
-export { AUTOMATION_MANIFEST_RELATIVE_PATH, AutomationInstallConflictError, AutomationUnsupportedHookBundleError, ORCHESTRATOR_HANDOFF_RELATIVE_PATH, TEAM_SYNC_STATE_RELATIVE_PATH, WORKFLOW_PLANS_RELATIVE_DIR, WORKFLOW_STATE_RELATIVE_PATH, archiveInactiveTeamSyncWork, autoArchiveTeamSyncState, buildAgenticHandoffMarkdown, buildAgenticTimeline, buildAgenticWorkStatus, buildAutomationInstallPlan, buildCanonicalEvent, buildCodeHooksInstallPlan, buildCodePromotionResult, buildCodeStatusResult, buildCodeSyncResult, buildHostedCodeOverlayUploadPayload, buildJournalCheckpointEntry, buildLocalCallersResult, buildLocalCodeOverlay, buildLocalImpactResult, buildLocalImportsResult, buildLocalNeighborsResult, buildLocalShortestPathResult, buildMemoryAudit, buildOnboardFolderManifest, buildOrchestratorHandoff, buildProjectIntelligenceBrief, buildSyncDocumentsDryRun, buildTeamSyncHandoffRecord, buildTeamSyncStartWorkRecord, buildTeamSyncSummary, buildToolCallPayload, buildToolResultPayload, buildVerificationPlan, buildWorkflowPhaseCommitSummary, buildWorkflowPlanScaffold, categoryFromGuardTag, classifyToolResult, collectSyncDocuments, collectSyncDocumentsInput, createClient, createEmptyTeamSyncState, createLocalQueryCache, detectReleaseSurfacesFromFiles, detectRuntimeEnvironment, extractCommandFromToolInput, extractFilesFromToolInput, formatOrchestratorRecommendationReason, formatStuckGuardDecision, getAutomationManifestPath, getAutomationStatus, getConfigPath, getLocalCodeOverlayCachePath, getLocalCodePromotionStatePath, getOrchestratorRecommendation, getPlanStepDisplayTitle, getStagedFiles, getStuckGuardInjection, getTeamSyncStatePath, installAutomationBundle, listProjectsForApiKey, loadAutomationManifest, loadConfig, loadTeamSyncState, memoryAuditCommand, memoryCleanCandidatesCommand, memoryCompactCommand, memoryHealthCommand, normalizeGuardTag, normalizeWorkflowPlanInput, projectIntelligenceBriefCommand, readLocalCodeOverlayCache, readLocalCodePromotionState, resolveQueryFromToolInput, runMemoryGuardCheck, saveConfig, saveTeamSyncState, shouldSuggestOrchestratorForWorkflow, shouldSuggestRuntimeForWorkflow, summarizeLocalCodeOverlay, teamSyncSweepCommand, verifyCommand, writeLocalCodeOverlayCache, writeLocalCodePromotionState, writeOrchestratorHandoff };
+export { AUTOMATION_MANIFEST_RELATIVE_PATH, AutomationInstallConflictError, AutomationUnsupportedHookBundleError, ORCHESTRATOR_HANDOFF_RELATIVE_PATH, TEAM_SYNC_STATE_RELATIVE_PATH, WORKFLOW_PLANS_RELATIVE_DIR, WORKFLOW_STATE_RELATIVE_PATH, archiveInactiveTeamSyncWork, autoArchiveTeamSyncState, buildAgenticHandoffMarkdown, buildAgenticTimeline, buildAgenticWorkStatus, buildAutomationInstallPlan, buildCanonicalEvent, buildCodeHooksInstallPlan, buildCodePromotionResult, buildCodeStatusResult, buildCodeSyncResult, buildHostedCodeOverlayUploadPayload, buildJournalCheckpointEntry, buildLocalCallersResult, buildLocalCodeOverlay, buildLocalImpactResult, buildLocalImportsResult, buildLocalNeighborsResult, buildLocalShortestPathResult, buildMemoryAudit, buildOnboardFolderManifest, buildOrchestratorHandoff, buildProjectIntelligenceBrief, buildSyncDocumentsDryRun, buildTeamSyncHandoffRecord, buildTeamSyncStartWorkRecord, buildTeamSyncSummary, buildToolCallPayload, buildToolResultPayload, buildVerificationPlan, buildWorkflowPhaseCommitSummary, buildWorkflowPlanScaffold, categoryFromGuardTag, classifyToolResult, collectSyncDocuments, collectSyncDocumentsInput, createClient, createEmptyTeamSyncState, createLocalQueryCache, detectReleaseSurfacesFromFiles, detectRuntimeEnvironment, extractCommandFromToolInput, extractFilesFromToolInput, formatOrchestratorRecommendationReason, formatStuckGuardDecision, getAutomationManifestPath, getAutomationStatus, getConfigPath, getLocalCodeOverlayCachePath, getLocalCodePromotionStatePath, getOrchestratorRecommendation, getPlanStepDisplayTitle, getStagedFiles, getStuckGuardInjection, getTeamSyncStatePath, ingestReferences, installAutomationBundle, listProjectsForApiKey, loadAutomationManifest, loadConfig, loadTeamSyncState, memoryAuditCommand, memoryCleanCandidatesCommand, memoryCompactCommand, memoryHealthCommand, normalizeGuardTag, normalizeWorkflowPlanInput, projectIntelligenceBriefCommand, readLocalCodeOverlayCache, readLocalCodePromotionState, referencesIngestCommand, referencesScanCommand, resolveQueryFromToolInput, runMemoryGuardCheck, saveConfig, saveTeamSyncState, scanReferences, shouldSuggestOrchestratorForWorkflow, shouldSuggestRuntimeForWorkflow, summarizeLocalCodeOverlay, teamSyncSweepCommand, verifyCommand, writeLocalCodeOverlayCache, writeLocalCodePromotionState, writeOrchestratorHandoff };