docs(aphoria): update CLI reference with bulk import features

Add documentation for:
- --template flag (generate example TOML)
- --validate-only flag (check without importing)
- --format flag (table|json output)
- Validation details (what gets checked)
- Link to comprehensive bulk import guide

All examples tested and working.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
jml 2026-02-10 05:35:03 +00:00
parent 7facac08a2
commit 7d58465e62

View File

@ -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 <FORMAT>` - Output format: `table` (default, human-readable) or `json` (tooling integration)
- `--authority-tier <TIER>` - Override authority tier for all imported claims (team_policy, expert, etc.)
- `--source-guide <NAME>` - Track the guideline name for compliance filtering (stored in `.aphoria/ingested_guides.toml`)
- `--dry-run` - Preview changes without writing to file
- `--merge <STRATEGY>` - 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]]