diff --git a/applications/aphoria/docs/cli-reference.md b/applications/aphoria/docs/cli-reference.md index be04e84..d47a78f 100644 --- a/applications/aphoria/docs/cli-reference.md +++ b/applications/aphoria/docs/cli-reference.md @@ -250,12 +250,21 @@ Deprecated claims are not verified but remain in the file for audit trail. ### `aphoria claims import` -Import claims in batch from a TOML file. +Import claims in batch from a TOML file with validation, reporting, and merge strategies. ```bash +# Generate template +aphoria claims import --template > my-claims.toml + +# Validate without importing +aphoria claims import my-claims.toml --validate-only + # Preview import (dry-run) aphoria claims import docs/guidelines.toml --dry-run +# Import with JSON output (for tooling) +aphoria claims import docs/guidelines.toml --format json + # Import with TeamPolicy tier aphoria claims import docs/guidelines.toml \ --authority-tier team_policy \ @@ -271,11 +280,27 @@ aphoria claims import docs/guidelines.toml \ ``` **Options:** +- `--template` - Generate example TOML template (omit FILE to use this) +- `--validate-only` - Check file format without importing +- `--format ` - Output format: `table` (default, human-readable) or `json` (tooling integration) - `--authority-tier ` - Override authority tier for all imported claims (team_policy, expert, etc.) - `--source-guide ` - Track the guideline name for compliance filtering (stored in `.aphoria/ingested_guides.toml`) - `--dry-run` - Preview changes without writing to file - `--merge ` - Merge strategy: `skip_existing` (default), `overwrite`, `fail_on_duplicate` +**Validation:** + +Pre-import validation catches errors before any writes: +- Invalid claim IDs (must be kebab-case: lowercase, hyphens only) +- Unknown authority tiers +- Empty required fields (provenance, invariant, consequence, category, created_by) +- Duplicate IDs within import file +- Duplicate concept_path+predicate combinations (warnings) + +All errors are reported at once with clear context (claim index, ID, field, error message). + +**See also:** [Bulk Import Guide](guides/bulk-claim-import.md) for complete documentation and examples. + **TOML Format:** ```toml [[claim]]