Tools Index

104 tools, grouped by filename prefix.

allocation

Tool	Description
allocation_apply.py	allocation_apply: per-student học-bổng allocation from the I6 rate table.

backup

Tool	Description
backup_registries.py	Checksum-verified, retention-pruned snapshots of the workspace SQLite stores.

bank

Tool	Description
bank_notification_extract.py	Extract NCB bank-notification emails into a draft-contribution batch + Drive evidence (donor/finance Area 3, the "email" capture lane — subplan track E).

beneficiary

Tool	Description
beneficiary_consistency_check.py	Cross-check that the SQLite registry, the markdown profiles, and the benefits-ledger directories on disk all agree (subplan §12-B4): every child.student_code has a profile file; every benefit row has a ledger file at ledger_path; every profile's programmes[].cohort_year matches its school's allocation block.
beneficiary_index_rebuild.py	Rebuild the three lookup indexes (subplan §8) + the quarterly cohort dashboard.
beneficiary_promote.py	Promote a raw intake drop into a structured Block-3 progress note on a beneficiary profile + a row in profile_entry (subplan §4 step 3).
beneficiary_registry_migrate.py	Create/upgrade so-dang-ky.sqlite — the Area-1 lineage system of record (child -> profile_entry, child -> benefit, child -> school_report, + watchlist_item).
beneficiary_validate.py	Validate a beneficiary profile (Block 1 + Block 2 frontmatter + Block 3 progress notes).

benefit

Tool	Description
benefit_record.py	Record one delivered benefit: write a ledger markdown entry under 10_Ho-so-thu-huong/So-phuc-loi/<journey-id>/ + insert a benefit row in so-dang-ky.sqlite (subplan §5 §9).
benefit_report.py	Aggregate benefit rows into per-month / per-programme / per-school / per-funding-source / per-petal rollups (subplan §6 §12-B3, design-HTML "How each report is published").

build

Tool	Description
build_index.py	Regenerate tools/INDEX.md: a docstring-derived catalog of every tool.

bundle

Tool	Description
bundle_state.py	Write-side helpers for STATUS.md — the state machine of a post-bundle.
bundle_validate.py	Validate a post-bundle (QC gate 1 — structural, blocking).

caption

Tool	Description
caption_draft.py	Claude Opus vision -> per-channel Vietnamese post copy (+ EN at milestones).

care

Tool	Description
care_auth.py	Single-administrator login for the care dashboard (trial scale).
care_benefit_extract.py	care_benefit_extract (N11, Track K): ingest a school funding agreement ("Thỏa thuận tài trợ" / BB tài trợ) into the care store.
care_intake_convert.py	Auto-convert intake job for Beneficiary Care (Flows A & B, trial scale).
care_mail.py	Capture care-document emails into the care intake inbox + Drive evidence (Area 1, the "email" intake lane — care-data-sync-backfill-plan §7, channel 3).
care_migrate.py	care_migrate: the idempotent, --dry-run-first migration CLI (plan Part 4/5).
care_rekey.py	care_rekey: STAGED Track G — re-key the care DB from journey_id to student_code.
care_reocr.py	care_reocr: a full, faithful re-transcription of a handwritten scan PDF.
care_roster.py	care_roster: read a Drive Danh sách roster (.xlsx) and propose new students.
care_roster_reconcile.py	care_roster_reconcile: apply coordinator roster-audit corrections to child.
care_source_review.py	care_source_review: detect a Drive source file edited since we copied it.

comment

Tool	Description
comment_store.py	Append-only comment thread for a field trip OR a survey case (#2).

content

Tool	Description
content_plan.py	Content plan — schema, reader, per-slot promote, read-time flags, photo lane.

contribution

Tool	Description
contribution_import_statement.py	Parse an NCB web-banking statement CSV into a draft contribution batch (subplan §7 step 2).
contribution_index_rebuild.py	Rebuild the by-donor/ index of the contribution ledger (subplan §4).
contribution_promote.py	Promote a resolved import batch into the registry (subplan §7 step 4).
contribution_receipt.py	Generate a per-contribution PDF receipt (subplan §9, §11 F-receipts).
contribution_receipt_annual.py	Optional year-end roll-up receipt (subplan §9.3, §11 F-receipts).
contribution_record.py	Record one cash contribution (subplan §4, §11 F2): write a con-YYYY-NNNNN.md file under 3_Nha-tai-tro/Lich-su-dong-gop/by-month/<YYYY-MM>/ and insert a contribution row in so-tai-chinh.sqlite.
contribution_webhook.py	Bank-credit webhook → matched contribution (integration-plan §8-E1).

create

Tool	Description
create_brief_form.py	Sync the Coordinator Brief Form's contents from the YAML spec.

dashboard

Tool	Description
dashboard_sync.py	Dashboard Sheet sync — the human-facing surface over STATUS.md (Đợt 2).

decisions

Tool	Description
decisions_core.py	Apply an administrator's Dashboard decision to a bundle (Đợt 2 core).

doctor

Tool	Description
doctor.py	Machine preflight: report what is actually installed/authed on THIS box.

donor

Tool	Description
donor_input_core.py	Core for the donor-input form pipeline (subplan §3a, §11 D1-form): map a Google-Form response row to a DonorInput, register the donor, and run the returning-donor detector so the Coordinator sees a merge candidate before acting.
donor_match.py	The returning-donor detector (subplan §3a.2, §11 D1).
donor_register.py	Register one donor (subplan §3, §11 D1): in one atomic step, insert a donor row in so-tai-chinh.sqlite, write the markdown profile under 3_Nha-tai-tro/Ho-so-nha-tai-tro/donor-D<NNNN>.md, and append a funding-source entry to nguon-tai-tro.yaml so a benefit (Area-1) can later reference this donor by code.
donor_validate.py	Validate a donor profile markdown's frontmatter (subplan §3, §11 D1): shape, opt-in coherence (no opt_in_*: true without an observed_at), valid enums (preferred_contact, observed_method, registration_source, primary_intent), and province against the vn-provinces-2025-07 list (+ Overseas).

email

Tool	Description
email_send.py	Outbound email seam — a Protocol + a Fake + a disabled-by-config SMTP sender.

event

Tool	Description
event_folder_core.py	Form-first event-folder creation (Cloud Run event-folder service core).
event_naming.py	Canonical event-slug + folder-name builder (naming-convention.md §Event slugs).

finance

Tool	Description
finance_anon_check.py	Anonymisation linter for published transparency drafts (subplan §8.3, §11 F5).
finance_entity_backfill.py	One-time finance-side entity backfill (dual-entity A-P3, plan §A7).
finance_registry_migrate.py	Create/upgrade so-tai-chinh.sqlite — the Areas 3 & 4 (donor + finance) system of record (donor -> contribution, donor -> inkind_contribution, inkind_contribution -> inkind_disposal, operating_cost, update_recipient, sponsorship_match).
finance_report_monthly.py	Generate the internal monthly CASH reconciliation report (subplan §8.1, §11 F4).
finance_report_publish.py	Assemble the published transparency report as a stream-D post-bundle (subplan §8.2, §11 F5).
finance_validate.py	Validate contribution + in-kind handover markdown frontmatter (subplan §4, §4.1, §11 F1): shape, valid enums (channel, intent, thank_you_channel, audit_source, disposal_status), VND amount sanity, and the donor-side funding_source ↔ donor-code cross-check against nguon-tai-tro.yaml.

forms

Tool	Description
forms_provision.py	Build a Google Form's questions from a form-spec YAML (Forms API batchUpdate).

gemini

Tool	Description
gemini_ocr.py	Shared Gemini structured-vision caller for the OCR/extract engines.

gworkspace

Tool	Description
gworkspace_check.py	Verify Domain-Wide Delegation against the Google Workspace APIs we use.

hub

Tool	Description
hub_reads.py	Read-only aggregations for the management-hub native views (P2).

improvement

Tool	Description
improvement_log.py	Append admin decision/edit signals to the monthly QC-log improvement register.

index

Tool	Description
index_registry.py	Maintain index/registry.sqlite — the asset-lineage system of record (asset -> rendition -> caption -> post -> performance, + audit).

ingest

Tool	Description
ingest_watch.py	Sync/poll the Google Shared Drive intake folder; dedup by SHA-256 of bytes.

inkind

Tool	Description
inkind_record.py	Record an in-kind handover and its disposals (subplan §4.1, §11 F2-inkind).
inkind_report_monthly.py	Generate the internal monthly IN-KIND report (subplan §8.4, §11 F4-inkind).

journey

Tool	Description
journey_leakage_check.py	Stream-C leakage gate (beneficiary-care-subplan §10, QC gate 8.5).

mailer

Tool	Description
mailer.py	Shared outbound-email lane (P29): the one place the workspace sends mail.

media

Tool	Description
media_count.py	Persisted per-event source-photo count.
media_retouch.py	Retouch photos for per-channel renditions: face-boosted smart-crop, per-aspect resize, watermark/logo overlay.
media_sanitise.py	Strip ALL EXIF + GPS from every ingested asset — the first transform, before any human or agent reads it.
media_triage.py	Cull the best assets from a bulk upload: PHash dedup → cluster into moments → composite per-image score → top N per cluster.

notify

Tool	Description
notify_bridge.py	Telegram approval bot — review/approve UX surface.

ocr

Tool	Description
ocr_intake.py	OCR intake for hand-filled / scanned student data (T18).

operating

Tool	Description
operating_cost_record.py	Record one operating cost (subplan §6, §8.1 §11 F3).

pg

Tool	Description
pg_migrate.py	Set up Postgres schemas on hmt-db and copy data from the 6 live SQLite DBs.

photo

Tool	Description
photo_polish.py	Gemini Nano Banana Pro -> corrective image polish + recipe sidecar.

pipeline

Tool	Description
pipeline_run.py	Headless post-bundle pipeline: sanitise → cull → retouch → caption → QC.

profile

Tool	Description
profile_store.py	Path-shaped storage seam for the Beneficiary-Care files (Đợt-3 cloud lift).

publish

Tool	Description
publish_pack.py	Stage-1 manual publishing pack.

qr

Tool	Description
qr_donor.py	Generate a per-donor VietQR (subplan §10, §11 D2).

report

Tool	Description
report_backfill.py	report_backfill: nightly reconciliation of legacy/CLI-generated reports.
report_child.py	Per-child report (subplan §6.1): identity / programme history / progress notes timeline / benefits ledger / 8-petal coverage / grade & attendance trend / followups outstanding / sibling cluster / Claude narrative.
report_cohort.py	Per-cohort report (subplan §6.2): one (programme, cohort_year) pair.
report_common.py	Shared building blocks for the three B5 reports (per-child, per-cohort, per-school): the ReportEngine Protocol seam (Anthropic + Fake), the audience filter, common petal/VND/markdown helpers.
report_index.py	report_index: a tiny status table for asynchronously-generated reports.
report_overall.py	Báo cáo tổng hợp (TH) — the all-programme, all-school roll-up (plan Part 4b).
report_render.py	Render ONE pending report end-to-end (child/school/cohort) and finalize it.
report_school.py	Per-school report (subplan §6.3): one partner school.

review

Tool	Description
review_site_build.py	Build a static HTML review surface for a post-bundle (offline; no network).
review_site_deploy.py	Push a built review-site directory to Cloudflare Pages as a preview deploy.

roster

Tool	Description
roster_match.py	Route OCR'd student records to roster profiles by name (T18).

safeguarding

Tool	Description
safeguarding_watchlist.py	Safeguarding watchlist signal-detection job (subplan §7).

school

Tool	Description
school_doc_extract.py	Structured-field extraction for the four school-side document types (subplan §4.1): học bạ / phiếu liên lạc, sổ điểm / bảng điểm, báo cáo họp phụ huynh, báo cáo chuyên cần.

score

Tool	Description
score_card_batch.py	Bulk score-card intake (P20): one upload of many school-doc PDFs, each matched to a student by filename, extracted in the background, then reviewed and committed through the existing per-student school_doc review path.

so

Tool	Description
so_tay.py	Sổ tay generator: compile a student's full handbook → a native Google Doc.

story

Tool	Description
story_archive.py	Archive an approved post's outputs to the Shared Drive 10_Cau-chuyen/ tree.

student

Tool	Description
student_summary.py	Per-school / per-cohort student summary — a native Google Sheet companion to the school/cohort report Doc.

survey

Tool	Description
survey_import.py	Bulk-create survey candidates from a school list (#1a).
survey_intake.py	Khảo sát — survey & selection subsystem (integration-plan §8-D).
survey_media_cache.py	Thumbnail cache for the survey candidate gallery (#2) — direct GCS blob API, deliberately NOT the gcsfuse mount.
survey_media_sanitise.py	Sweep every survey candidate's photos/videos for surviving EXIF/GPS and strip them (safeguarding.md measure 1) — the server-side catch-all for whatever the browser's client-side JPEG strip in survey_capture.html couldn't cover: video, HEIC, PNG, and any parsing miss.
survey_media_thumb.py	Pillow-only fallback thumbnail for the survey candidate gallery (#2).

template

Tool	Description
template_doc.py	Generate a branded Google Doc from a document-chrome template.

thank

Tool	Description
thank_you_draft.py	Draft a personal thank-you for one contribution (subplan §7 step 5, §11 D3).
thank_you_record.py	Stamp a contribution / in-kind handover as thanked + receipted in ONE step (subplan §7 step 5, §11 D3).

trao

Tool	Description
trao_gui_onboard.py	trao_gui_onboard: dry-run onboarding of the Trao gửi yêu thương roster (I11).

update

Tool	Description
update_recipient_register.py	Subscribe a donor to an opt-in update list + regenerate the list markdown (subplan §5, §11 D4).
update_recipient_unsubscribe.py	Unsubscribe a donor from an update list (subplan §5, §11 D4).
update_send_batch.py	Produce the CSV the Coordinator pastes into a mail client (subplan §5, §11 D4).

video

Tool	Description
video_edit.py	ffmpeg video pipeline: trim, EBU R128 loudness normalise to -14 LUFS, burn-in subtitles, intro/outro bumper concat.