Resolving locale, route permissions, and workspace projection.
Current scope: Guest
Category: 10_normative | Version: v1.0.0
Owner: DOCUMENT_CUSTODIAN | Review cycle: 90 days
Approval authority: GOVERNANCE_ADMIN
Documentation portal is read-only. Editing and mutation endpoints are disabled.
Kvary platform is originally created in Georgian. Where a Georgian version exists, Georgian is authoritative for platform UI, documentation, and legal interpretation.
Translations into other languages are provided for convenience. Some records may originate in other languages and carry their own source or legal locale for a specific flow, but where a Georgian version is available, the Georgian version prevails for platform-level wording and interpretation.
Metadata incomplete: Document ID, Version, Status, Owner Role, Last Review Date, Next Review Date, Change Log
Preferred ingestion path is deterministic parser (xlsx -> JSON payload -> upsert).
Use RAG/chunking only for semantic search and assistant UX, not as source-of-truth ingest.
butkhuzi_norms supports localized titles via title_i18n JSON map.
Upsert payload row can include:
{
"title": "Основной заголовок",
"titleI18n": {
"ru": "Основной заголовок",
"en": "Primary heading",
"ka": "ძირითადი სათაური"
}
}
Component rows can also include localized labels via components[].labelI18n.
127.0.0.1:5432services/api and services/svc-tenders)openpyxl is required for XLSX parser)/mnt/c/Users/User/Downloads/სახარჯთაღრიცხვო გაანგარიშება_ ტომი V-2.xlsxnpm --prefix services/svc-tenders run migrate
This creates butkhuzi_norms table.
npm run butkhuzi:build-payload:xlsx -- \
--inputXlsx "/mnt/c/Users/User/Downloads/სახარჯთაღრიცხვო გაანგარიშება_ ტომი V-2.xlsx" \
--sourceVersion "SNIP-2026-Q1"
Outputs:
tmp/outputs/butkhuzi_upsert_payload_xlsx.json (or custom --output)tmp/outputs/butkhuzi_build_report_xlsx.json (or custom --report)Direct python invocation (WSL-safe):
python3 scripts/butkhuzi-build-payload-xlsx.py \
--inputXlsx "/mnt/c/Users/User/Downloads/სახარჯთაღრიცხვო გაანგარიშება_ ტომი V-2.xlsx" \
--sourceVersion "SNIP-2026-Q1" \
--output "tmp/outputs/butkhuzi_upsert_payload_v2_xlsx.json" \
--report "tmp/outputs/butkhuzi_build_report_v2_xlsx.json"
npm run butkhuzi:build-payload -- --sourceVersion "SNIP-2026-02"
Optional (fast test on first files only):
npm run butkhuzi:build-payload -- --maxFiles 3
npm run butkhuzi:upsert
Upsert custom payload path (recommended after XLSX parse):
npm run butkhuzi:upsert -- --input tmp/outputs/butkhuzi_upsert_payload_v2_xlsx.json
Dry run:
npm run butkhuzi:upsert -- --dry-run
Default URL:
http://localhost:4001/api/v1/butkhuzi/upsertNotes:
sourceVersion is strongly recommended per import batch (for example: SNIP-2026-Q1).UNVERSIONED.Direct svc-tenders URL:
npm run butkhuzi:upsert -- --url http://localhost:4020/butkhuzi/upsert
curl "http://localhost:4001/api/v1/butkhuzi/norms?page=1&pageSize=20&sourceKey=SNIP&sourceVersion=SNIP-2026-Q1"
curl "http://localhost:4001/api/v1/butkhuzi/suggest?query=1-1&limit=10&sourceKey=SNIP&sourceVersion=SNIP-2026-Q1"
npm run butkhuzi:smoke
After norms are upserted, rebuild chunk index:
curl -X POST "http://localhost:4001/api/v1/butkhuzi/chunks/rebuild" \
-H "content-type: application/json" \
-d '{"sourceKey":"SNIP","sourceVersion":"SNIP-2026-Q1"}'
Search chunks:
curl "http://localhost:4001/api/v1/butkhuzi/search?query=экскаваторы&sourceKey=SNIP&sourceVersion=SNIP-2026-Q1&page=1&pageSize=25"