Description
Markdown Import and Incremental Indexing turns an existing folder of documents into maintained Dotabase rows without requiring users to hand-author API payloads. dots dotabases import-markdown sends a stable recursive corpus in bounded batches, while dots dotabases index computes source paths and SHA-256 hashes, reads a body-free source index, and submits only new or changed files. Per-file failures are collected without abandoning later work.
The workflow is designed for operators and coding agents. It uses the same authenticated, company-scoped service contracts as the rest of Dots, so terminal or protocol convenience never creates a second source of truth. Inputs are validated before or at the route boundary, and outputs preserve identifiers and structured details needed for a reliable next step.
Selling Points
- Avoids re-uploading unchanged documents, making repeat synchronization predictable and economical.
- Preserves row identity on changed files through the shared normalizing import route.
- Lets operators exclude generated files and stamp typed defaults across every imported row.
- Supports custom normalizers and behavior suppression for corpus-specific ingestion policy.
- Can defer provider-backed enrichment so large imports return before background processing drains.
User Story
A team points the CLI at a maintained Markdown handbook, excludes generated agent notes, applies a typed department property, and runs the indexer. On the next run, only one edited file is updated, unchanged rows are skipped, and the summary identifies every action and any isolated failure. The result is a concrete, inspectable outcome that another person or automation can continue from without reconstructing hidden state.
Extension Surface
The CLI workflow is automatable: packages/cli/src/commands/dotabases.ts binds all import and index flags. Normalizer selection makes the underlying ingestion configurable, but the command family has no external verb-registration seam. The rating reflects the most-open supported seam that is true for this capability, not a transitive implementation detail. The cited path is the operational proof: consumers can use the documented seam, while unsupported changes still require a core release.
Capabilities & Limits
- Capability: One-shot recursive Markdown import with bounded batching and per-file error collection.
- Capability: Hash-based create, update, and skip reconciliation through a lightweight source index.
- Capability: Excludes, typed defaults, behavior suppression, normalizer overrides, and deferred enrichment.
- Limit: The input surface is a local Markdown tree; binary sources and connector-managed remote systems use separate ingestion capabilities.
The limit is intentional product truth rather than missing documentation. Calls also remain subject to authentication, tenant selection, schema validation, and the permissions enforced by the authoritative service.
Implementation Map
packages/cli/src/commands/dotabases.tspackages/cli/src/import-enrichment.tsdocs/cli/dotabases-commands.md