Metadata-Version: 2.4
Name: ask-just
Version: 0.1.10
Summary: Thin CLI for the hosted Ask Just source plane
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# Ask Just

Ask Just is the first source-backed company model of Just.

The `ask-just` CLI and hosted API remain the stable technical surface for
compatibility. Ask Just is the model identity above that source plane: verified
source lanes, provenance rows, source-routing rules, correction memory, Deep
Research bundles, and governed action boundaries.

The goal is simple: a teammate should be able to ask Just what it knows, inspect
the evidence, challenge the answer, and improve the memory as new artifacts
appear.

## Teammate Setup

Install Ask Just for a teammate with one command:

```bash
uvx ask-just setup --code JST-MZ6X-F56K
```

The code is stable until Josh or an admin rotates it. This command installs or
refreshes the persistent CLI, exchanges the setup code, configures Codex and
Claude Code, runs doctor, runs the canonical verification query, and reports
the source id.

Under the hood, Ask Just does not ask a live app, SharePoint folder, exported
row set, or loose pile of files every time. It follows the source contract:

```text
map the source -> access it -> enumerate it where needed -> parse it into atomic units or live-query proof records -> verify receipts -> make it queryable
```

Once a source passes that gate, normal Ask Just answers come through the hosted
API backed by the GCP VM source index with provenance. That is what makes
answers fast, repeatable, and inspectable without turning local rebuild
artifacts into answer fallbacks.

Read [SPEC.md](SPEC.md) for the deeper product contract and future direction.
Read [docs/ask-just-model-card.md](docs/ask-just-model-card.md) for the model card
and [docs/ask-just-release-notes.md](docs/ask-just-release-notes.md) for release
history.
Read [docs/ask-monarch-flow-map.md](docs/ask-monarch-flow-map.md) for the
piece-by-piece mapping from Monarch-1 to Ask Just.
Read [docs/source-receipts/completion-audit.md](docs/source-receipts/completion-audit.md)
for the phase audit behind the current source-plane claim.
Read [docs/full-source-completion-frontier.md](docs/full-source-completion-frontier.md)
for what is active now and what is explicitly not yet claimed.

## Architecture

Ask Just has two flows: source onboarding builds the verified SQLite/FTS index
on the VM, and the `ask-just` CLI calls the hosted API to ask that index for
evidence.

![Ask Just architecture](docs/ask-just-architecture.png)

## Source Lane Change Rule

Every new answerable source lane must update the product contract and the
explainable architecture in the same change. A lane is not done if it only
appears in parser code or source maps.

For each new source id, update:

- `config/all-source-ids.json`, `config/queryable-source-ids.json`, and
  `config/fresh-source-map.yaml`
- `config/source-capabilities.yaml`, which declares what each source is allowed
  to answer and what must fail closed
- `config/child-source-registry.json` and
  `config/semantic-child-source-registry.json`, which give manifest children
  and semantic business lanes stable planner-facing source ids
- parser code, receipts, hosted VM SQLite verification, and freshness proof
- `README.md`, `SPEC.md`, and `ARCHITECTURE.md`
- `docs/ask-just-architecture.svg` and the rendered
  `docs/ask-just-architecture.png`

## Visual Explainers

Ask Just's architecture explainer is a repo-owned static SVG rendered to PNG.
The SVG is the editable source; the PNG is the README-facing asset.

```bash
sips -s format png docs/ask-just-architecture.svg --out docs/ask-just-architecture.png
```

Use these visuals to explain product boundaries like:

```text
ask-just CLI -> HTTPS JSON API -> VM SQLite -> sourced answer
```

If the API is unavailable, the correct behavior is to fix the API path, not to
answer through SSH or direct SQLite.

## Current State

## Ask Just Actions

Ask Just is also the home for company actions. Actions are not separate agents,
managed-agent runtimes, bots, or sidecar operators. Ask Just is the company
brain, hands, and arms: it reads source-grade inputs, drafts an operational
decision, asks for human approval where the action is risky or external, executes
through owned tools, and writes receipts back into the source plane.

Order allocation is the first declared action candidate. Its source boundary is
`operations_order_allocation`, which is declared but not queryable until the
daily inventory, demand, routing, inbound, human-review, and NetSuite commit
evidence is mapped, parsed, receipted, and exposed through the hosted API.

The v0 command surface is deliberately inside Ask Just:

```bash
ask-just actions order-allocation prepare --run-date 2026-05-06
ask-just actions order-allocation rehearse --run-date 2026-05-06
ask-just actions order-allocation process-approved --run-date 2026-05-06
ask-just actions order-allocation status RUN_ID
ask-just actions order-allocation receipts RUN_ID
```

Until the source lane is fresh and atomically queryable, these commands must
fail closed with freshness and repair instructions rather than drafting from
raw mail, Evista, NetSuite, SharePoint, local files, or chat context.
`rehearse` is the safe practice surface: it uses the same source freshness gate
as a real allocation pass, but returns a no-commit practice packet with
NetSuite writes, approved-artifact processing, and external sends disabled.

Prepare-time source proof records land here:

```text
source-material/operations_order_allocation/source-family-proofs/*.json
```

The builder materializes them as
`operations_order_allocation_source_family_proofs` rows. The first supported
families are `inventory_vernon`, `inventory_bethlehem`,
`inventory_vertical_evista`, `netsuite_open_orders`, `routing_rules`, and
`operations_inbound_log`.

Capture helper:

```bash
python3 scripts/capture_order_allocation_source_proofs.py mailbox-inventory --family-id inventory_vernon --freshness-date 2026-05-06
python3 scripts/capture_order_allocation_source_proofs.py mailbox-inventory --family-id inventory_bethlehem --freshness-date 2026-05-06
python3 scripts/capture_order_allocation_source_proofs.py evista-inventory --freshness-date 2026-05-06
python3 scripts/capture_order_allocation_source_proofs.py sharepoint-file --family-id routing_rules --freshness-date 2026-05-06 --drive-id DRIVE_ID --item-id ITEM_ID --source-uri "sharepoint:/sites/operations/Shared Documents/Automation/OOR Automation - Customer and Carrier tables.xlsx"
python3 scripts/capture_order_allocation_source_proofs.py sharepoint-file --family-id operations_inbound_log --freshness-date 2026-05-06 --drive-id DRIVE_ID --item-id ITEM_ID --source-uri "sharepoint:/sites/operations/Shared Documents/Inbound Log/Inbound Log 2026.xlsx"
python3 scripts/capture_order_allocation_source_proofs.py netsuite-open-orders --freshness-date 2026-05-06 --run-date 2026-05-06
python3 scripts/build_fresh_source_database.py --source-id operations_order_allocation
```

`evista-inventory` requires `VERTICAL_USER`/`VERTICAL_PASS` or
`EVISTA_USERNAME`/`EVISTA_PASSWORD` in the Ask Just VM refresh environment.
`mailbox-inventory` inherits the previous order-allocation Microsoft Graph
shape (`GRAPH_TENANT_ID`, `GRAPH_CLIENT_ID`, `GRAPH_CLIENT_SECRET`) as well as
the Ask Just `MS_*` aliases. Vernon defaults to
`noreply@onelineage.com` plus `Inventory Stock Summary Report`; Bethlehem
defaults to `no-reply-powerbi@microsoft.com` plus
`Eat Just Fulfillment On Hand Report`. For local operator runs, pass
`--env-file /path/to/order-allocation.env` rather than copying secrets into the
repo.

Run NetSuite capture in the Ask Just runtime/VM credential context. Ask Just has
NetSuite read/write access; a laptop shell missing `NETSUITE_*` is only a local
execution-context issue.

## Current State

Ask Just's answerable data lives behind the hosted API in the active GCP VM
SQLite source index. Exact answers must come from rows returned by `ask-just`;
repo docs, maps, receipts, local rebuild artifacts, and tests describe or
verify that index, but they are not answer data.

The active source inventory is generated, not hand-maintained:

- Declared source ids: `config/all-source-ids.json`
- Ask-surface source ids: `config/queryable-source-ids.json`
- Answerability and capability registry: `config/source-capabilities.yaml`
- Strict lane table: `docs/strict-source-completion-table.md`
- Current external blockers: `docs/source-required-inputs.md`
- Completion audit: `docs/source-goal-completion-audit.md`

`ops_resources_directory` is a source manifest, not a closed source plane by
itself. Its workbook rows are queryable evidence for the directory, including
the `Reports and Portals` sheet and the `Comans` partner/contact sheet. A full
`$just-source` claim for that lane additionally requires source closure for
every non-empty Column E target and for every login-backed or related link
behind those targets. The focused audit lives at
`docs/source-receipts/ops-resources-directory-transitive-source-audit.md` and
feeds `python3 scripts/verify_source_goal_complete.py`.

As of the Scorecard child-surface refresh, Ask Just declares 119 source lanes in
`config/all-source-ids.json`; 116 are intended for the Ask surface in
`config/queryable-source-ids.json`. `tofutown_qvd_last_90_days`,
`tofutown_employee_list_2026`, and `teams_daily_product_sync` are deliberately
declared but not queryable.
`tofutown_qvd_last_90_days` waits on current QVD file access and row parsing
inside the rolling 90-day window. `operations_order_allocation` waits on source
grade daily inventory, demand, routing, inbound, human-review, and commit
evidence. The Qlik app-model snapshot lane and Dirk stock/service-level workbook
lane are scoped to last-90-day evidence. `tofutown_production_planning_folder`
is partially queryable for declared folder-boundary lookup and still needs
deeper hosted TofuTown folder refresh proof for full operational answers.
`teams_daily_product_sync` waits on a Teams transcript parser and receipt gate.
`tofutown_germany_retail_tracker` is
the exact Germany Tracker SharePoint drive item for Germany retail/key-account
facts, with hosted rows live now and daily VM refresh pending a TofuTown tenant
Graph reader on the VM. The four TofuTown / Just Europe finance workbook lanes
and TofuTown people-operations lanes remain separate source boundaries. `operations_logistics_otif_2024v2`
covers the exact Operations / ALLOCATION workbook and its revised OT/IF/OTIF
formula cells and threaded comments; Scorecard remains canonical for plain KPI
values unless the user asks for workbook calculation mechanics.

Every source lane must carry a freshness contract: source of truth, declared
boundary, query plane, freshness mechanism/cadence, last checked/refreshed
proof, stale behavior, and whether it is current-truth or snapshot-only. SPINS
lanes are delivered reporting snapshots keyed to the workbook data ending date.
Every non-SPINS lane must refresh daily at midnight America/Los_Angeles through
the VM timer or an equivalent source-specific delta proof before current-truth
answers.

## Deep Research Max Contract

Deep Research Max must cover every shared verified Ask Just source lane before
launch. The lane list is generated from the hosted `ask-just sources` surface
and cross-checked against `config/queryable-source-ids.json`, not from a
prompt-specific "relevant lanes" list or any manual checklist.

The launch preflight must stop before launching Gemini if any shared verified
source lane is missing from the hosted Ask Just `/sources` surface, lacks the
required `mapped`, `accessible`, and `atomically_queryable` gates, has no
freshness contract, has no hosted source-file receipt rows, or has no hosted
atomic rows. The evidence bundle must include `source_lanes_covered` with the
full generated lane list. Relevance affects row selection and ranking inside
each lane; it does not affect lane coverage.

Personal/private overlays stay excluded from Deep Research Max unless they have
been promoted into the shared verified source lane inventory. A user's personal
mailbox overlay, for example, is not part of the team-visible source plane and
must not be pulled into the bundle.

Dry bundle-only proof:

```bash
python3 scripts/deep_research_just.py --bundle-only --row-limit 0
```

| Source id | Layer | Query plane | Freshness contract | Ask surface |
| --- | --- | --- | --- | --- |
| `rd_powerjacks_formulations` | r_and_d | `sharepoint_workbook_snapshot` | `daily_midnight_snapshot_check` | yes |
| `rd_formulations_vault_production_formulas` | r_and_d_production_formulas | `sharepoint_document_library` | `daily_midnight_sharepoint_graph_recursive_refresh` | yes |
| `spins_plant_based_meat_powertabs` | sales_and_retail_velocity | `local_xlsb_workbook_snapshot` | `scheduled_snapshot` | yes |
| `spins_breakfast_powertabs` | sales_and_retail_velocity | `local_xlsb_workbook_snapshot` | `scheduled_snapshot` | yes |
| `spins_condiments_powertabs` | sales_and_retail_velocity | `local_xlsb_workbook_snapshot` | `scheduled_snapshot` | yes |
| `spins_protein_powder_powertabs` | sales_and_retail_velocity | `local_xlsb_workbook_snapshot` | `scheduled_snapshot` | yes |
| `operations_production_plan_latest` | operations_planning | `sharepoint_xlsx_workbook_snapshot` | `daily_midnight_graph_delta_snapshot` | yes |
| `ejp_protein_release_tracker` | quality_and_batch_release | `sharepoint_xlsx_workbook_snapshot` | `daily_midnight_graph_delta_snapshot` | yes |
| `ejp_production_wow` | ejp_protein_production | `sharepoint_xlsx_workbook_snapshot` | `daily_midnight_graph_delta_snapshot` | yes |
| `ejp_yield_2023` | ejp_protein_yield | `sharepoint_xlsx_workbook_snapshot` | `daily_midnight_graph_delta_snapshot` | yes |
| `protein_logistics_2025` | protein_raw_material_logistics | `sharepoint_xlsx_workbook_snapshot` | `daily_midnight_graph_delta_snapshot` | yes |
| `operations_inbound_log` | operations_logistics | `sharepoint_xlsx_workbook_snapshot` | `daily_midnight_graph_delta_snapshot` | yes |
| `quality_vault_finalized_sops` | quality_and_batch_release | `sharepoint_document_library` | `daily_midnight_sharepoint_graph_recursive_refresh` | yes |
| `rd_processdev_egb_sops` | r_and_d_quality_sops | `sharepoint_document_library` | `daily_midnight_sharepoint_graph_recursive_refresh` | yes |
| `rd_processdev_project_onestream` | r_and_d_processdev_projects | `sharepoint_document_library` | `daily_midnight_sharepoint_graph_recursive_refresh` | yes |
| `operations_order_allocation` | operations_order_allocation | `declared_multi_system_order_allocation_boundary` | `daily_midnight_mailbox_evista_netsuite_sharepoint_refresh` | declared gap; not queryable |
| `operations_logistics_otif_2024v2` | operations_logistics | `sharepoint_xlsx_workbook_snapshot` | `daily_midnight_graph_delta_snapshot` | yes |
| `operations_logistics_allocation_planning_2026` | operations_logistics | `sharepoint_xlsx_drive_item` | `daily_midnight_sharepoint_graph_drive_item_refresh` | yes |
| `tofu_town_production_planning` | tofu_town_operations | `local_xlsx_workbook_set_snapshot` | `daily_midnight_delivered_snapshot_check` | yes |
| `tofutown_production_planning_folder` | tofu_town_operations | `sharepoint_document_library` | `on_demand_tofutown_azure_cli_sharepoint_graph_refresh` | declared gap; not queryable |
| `tofutown_qlik_cloud_app_models` | tofutown_operations_data_lineage | `qlik_cloud_app_query_export_snapshot` | `weekly_saturday_midnight_current_qlik_api_snapshot_last_90_days_only` | yes |
| `tofutown_qvd_last_90_days` | tofutown_operations_qvd_facts | `qlik_qvd_file_contents` | `weekly_saturday_midnight_current_qvd_file_pull_last_90_days_only` | declared gap; not queryable |
| `tofutown_dirk_stock_level_workbook` | tofutown_operations_stock_service_level | `sharepoint_xlsx_workbook_snapshot_last_90_days` | `weekly_saturday_midnight_sharepoint_workbook_snapshot_last_90_days_only` | yes |
| `weekly_tofutown_just_europe_sales` | weekly_tofutown_just_europe_sales | `local_xlsb_workbook_snapshot` | `weekly_delivered_navision_sales_export_snapshot` | declared only; source-surface gap |
| `tofutown_germany_retail_tracker` | tofutown_germany_retail | `sharepoint_xlsx_drive_item` | `daily_midnight_sharepoint_graph_drive_item_refresh_pending_tofutown_vm_reader` | yes |
| `tofutown_standard_cost_gross_margin_by_sku_2026_05` | tofutown_just_europe_finance | `sharepoint_xlsx_workbook_snapshot` | `daily_midnight_delivered_snapshot_check_until_tofutown_graph_refresh` | yes |
| `tofutown_bom_tt_skus` | tofutown_just_europe_finance | `sharepoint_xlsx_workbook_snapshot` | `daily_midnight_delivered_snapshot_check_until_tofutown_graph_refresh` | yes |
| `tofutown_financial_tracking_week_18` | tofutown_just_europe_finance | `sharepoint_xlsx_workbook_snapshot` | `daily_midnight_delivered_snapshot_check_until_tofutown_graph_refresh` | yes |
| `tofutown_preliminary_pl_march_2026` | tofutown_just_europe_finance | `sharepoint_xlsx_workbook_snapshot` | `daily_midnight_delivered_snapshot_check_until_tofutown_graph_refresh` | yes |
| `just_us_canada_p_and_l_boms` | just_us_canada_finance_bom | `sharepoint_document_library` | `daily_midnight_sharepoint_graph_recursive_refresh` | yes |
| `qualification_fold_sensory` | r_and_d_quality_sensory | `sharepoint_xlsx_workbook_snapshot` | `daily_midnight_graph_delta_snapshot` | yes |
| `qualification_meat_sensory` | r_and_d_quality_sensory | `sharepoint_xlsx_workbook_snapshot` | `daily_midnight_graph_delta_snapshot` | yes |
| `qualification_v5_sensory_analytics` | r_and_d_quality_sensory | `sharepoint_xlsx_workbook_snapshot` | `daily_midnight_graph_delta_snapshot` | yes |
| `rd_in_market_testing` | r_and_d_quality_sensory | `sharepoint_xlsx_workbook_snapshot` | `daily_midnight_graph_delta_snapshot` | yes |
| `rd_liquid_egg_v6` | r_and_d_formulation | `sharepoint_xlsx_workbook_snapshot` | `daily_midnight_graph_delta_snapshot` | yes |
| `reefer_meat_shelf_life_tests` | r_and_d_quality_shelf_life | `sharepoint_xlsx_workbook_snapshot` | `daily_midnight_graph_delta_snapshot` | yes |
| `target_tracker` | sales_planning_and_retail_performance | `sharepoint_xlsx_workbook_snapshot` | `daily_midnight_graph_delta_snapshot` | yes |
| `finance_cash_flow_forecast_2026` | finance_accounts_payable_cash_flow | `sharepoint_xlsx_workbook_snapshot` | `daily_midnight_graph_delta_snapshot` | yes |
| `operations_dashboard_2025` | operations_dashboard | `sharepoint_xlsx_workbook_snapshot` | `daily_midnight_graph_delta_snapshot` | yes |
| `appleton_jpc_factory_dashboard` | appleton_factory_operations | `external_http_jpc_factory_api_snapshot` | `daily_midnight_http_api_snapshot` | yes |
| `whole_foods_canada_just_egg_rl_upsw` | sales_and_retail_velocity | `sharepoint_xlsx_workbook_snapshot` | `daily_midnight_graph_delta_snapshot` | yes |
| `whole_foods_us_who_cube_2026_04_19` | sales_and_retail_velocity | `sharepoint_xlsx_workbook_snapshot` | `daily_midnight_graph_delta_snapshot` | yes |
| `whole_foods_us_who_cube_2026_05_10` | sales_and_retail_velocity | `local_xlsx_workbook_snapshot` | `delivered_who_cube_snapshot_replace_on_new_workbook` | yes |
| `whole_foods_us_who_cube_2026_05_31` | sales_and_retail_velocity | `local_xlsx_workbook_snapshot` | `delivered_who_cube_snapshot_replace_on_new_workbook` | yes |
| `dot_foodservice_weekly_sales` | foodservice_sales | `local_xlsx_workbook_snapshot` | `weekly_delivered_dot_foodservice_sales_report_snapshot` | yes |
| `ops_resources_external_login_portals` | operations_resources_directory | `external_login_portal_endpoint_proof` | `daily_midnight_http_endpoint_probe_from_ops_resources_directory` | yes |
| `ops_resources_netsuite_saved_searches` | operations_resources_directory | `live_netsuite_saved_search_metadata_proof` | `daily_midnight_suiteql_saved_search_metadata_from_ops_resources_directory` | yes |
| `ops_resources_bean_movements_financial_review` | operations_resources_directory | `sharepoint_xlsx_drive_item` | `daily_midnight_sharepoint_graph_drive_item_refresh` | yes |
| `ops_resources_coman_weekly_agenda_select_folder` | operations_resources_directory | `sharepoint_document_library` | `daily_midnight_sharepoint_graph_recursive_refresh` | yes |
| `ops_resources_coman_weekly_agenda_slides_folder` | operations_resources_directory | `sharepoint_document_library` | `daily_midnight_sharepoint_graph_recursive_refresh` | yes |
| `ops_resources_month_end_bol_for_comans_folder` | operations_resources_directory | `sharepoint_document_library` | `daily_midnight_sharepoint_graph_recursive_refresh` | yes |
| `ops_resources_logistics_cross_border_docs_folder` | operations_resources_directory | `sharepoint_document_library` | `daily_midnight_sharepoint_graph_recursive_refresh` | yes |
| `ops_resources_mlg_inventory_report_power_jacks` | operations_resources_directory | `sharepoint_xlsx_drive_item` | `daily_midnight_sharepoint_graph_drive_item_refresh` | yes |
| `ops_resources_select_customs_issue_folder` | operations_resources_directory | `sharepoint_document_library` | `daily_midnight_sharepoint_graph_recursive_refresh` | yes |
| `ops_resources_select_joseph_inventory_email` | operations_resources_directory | `microsoft_graph_mail_artifact_snapshot` | `bounded_graph_mail_artifact_snapshot_refresh` | yes |
| `ops_resources_trenton_coman_report_emails` | operations_resources_directory | `microsoft_graph_mail_artifact_snapshot` | `bounded_graph_mail_artifact_snapshot_refresh` | yes |
| `ops_resources_procurement_tracker` | operations_resources_directory | `sharepoint_xlsx_drive_item` | `daily_midnight_sharepoint_graph_drive_item_refresh` | yes |
| `ops_resources_operations_budget_actuals_2025_2026` | operations_resources_directory | `sharepoint_xlsx_drive_item` | `daily_midnight_sharepoint_graph_drive_item_refresh` | yes |
| `ops_resources_spv_invoice_tracker_2021` | operations_resources_directory | `sharepoint_xlsx_drive_item` | `daily_midnight_sharepoint_graph_drive_item_refresh` | yes |
| `ops_resources_weekly_demand_w20_2026` | operations_resources_directory | `sharepoint_pptx_drive_item` | `daily_midnight_sharepoint_graph_drive_item_refresh` | yes |
| `ops_resources_nmiles_2026_forecast_folder` | operations_resources_directory | `sharepoint_document_library` | `daily_midnight_sharepoint_graph_recursive_refresh` | yes |
| `team_sales_dot_retail_reports_folder` | retail_sales_reports | `sharepoint_document_library` | `daily_midnight_sharepoint_graph_recursive_refresh` | yes |
| `finance_deductions_backup_root_folder` | finance_deductions | `sharepoint_document_library` | `daily_midnight_sharepoint_graph_recursive_refresh_metadata_only_archive_root` | yes |
| `finance_deduction_tracking_folder` | finance_deductions | `sharepoint_document_library` | `daily_midnight_sharepoint_graph_recursive_refresh` | yes |
| `team_sales_shelf_life_tracker_by_customer` | sales_order_shelf_life | `sharepoint_xlsx_drive_item` | `daily_midnight_sharepoint_graph_drive_item_refresh` | yes |
| `team_sales_shipment_tracker_foodservice` | foodservice_sales | `sharepoint_xlsx_drive_item` | `daily_midnight_sharepoint_graph_drive_item_refresh` | yes |
| `satellite_cpg_eat_just_brochure` | brand_sales_materials | `external_web_app_brochure_snapshot` | `daily_midnight_http_api_snapshot` | yes |
| `just_phase_3b_proposal` | strategic_project_proposals | `local_pdf_document_snapshot` | `delivered_pdf_snapshot` | yes |
| `block_from_hierarchy_to_intelligence` | operating_model_reference | `external_web_html_snapshot` | `daily_midnight_http_delta` | yes |
| `just_public_website_homepage` | public_website_and_brand | `external_web_html_snapshot` | `daily_midnight_http_delta` | yes |
| `asana_work_management` | work_management | `external_asana_workspace_project_snapshot` | `daily_midnight_api_delta` | yes |
| `replace_enter_repo_github` | formulation_nutrition_and_labels | `github_repo_snapshot_with_live_app_api_and_local_feed_artifacts` | `daily_midnight_git_delta` | yes |
| `brand_logo_eat_just_svg` | brand_assets | `local_brand_asset_snapshot` | `daily_midnight_delta_or_equivalent_origin_pending` | yes |
| `brand_font_neue_haas_grotesk_display_round_zip` | brand_assets | `local_brand_asset_zip_snapshot` | `daily_midnight_delta_or_equivalent_origin_pending` | yes |
| `hr_just_food_company_headcount` | people_operations | `local_xlsx_workbook_snapshot` | `daily_midnight_delivered_snapshot_check` | yes |
| `tofutown_employee_list_2026` | people_operations | `sharepoint_xlsx_workbook_snapshot` | `daily_midnight_sharepoint_workbook_snapshot` | yes |
| `wecare_mailbox_last_30_days` | customer_experience | `live_microsoft_graph_mailbox` | `daily_midnight_graph_delta_equivalent_rolling_30_days` | yes |
| `just_meat_production_library` | just_meat_production | `sharepoint_document_library` | `daily_midnight_graph_delta_after_recursive_enumeration` | yes |
| `rd_process_sciences_lab_research` | r_and_d_process_sciences | `sharepoint_document_library` | `daily_midnight_graph_delta_after_recursive_enumeration` | yes |
| `rd_process_sciences_yield_improvement` | r_and_d_process_sciences | `sharepoint_document_library` | `daily_midnight_graph_delta_after_recursive_enumeration` | yes |
| `scorecard_monthly_data` | company_kpis | `live_scorecard_api` | `daily_midnight_current_truth_snapshot` | yes |
| `scorecard_ops_metrics` | operations_kpis | `live_scorecard_api` | `daily_midnight_current_truth_snapshot` | yes |
| `scorecard_retail_velocity` | retail_velocity | `live_scorecard_api` | `daily_midnight_current_truth_snapshot` | yes |
| `scorecard_sales_rankings` | sales_rankings | `live_scorecard_api` | `daily_midnight_current_truth_snapshot` | yes |
| `scorecard_sku_pnl` | sku_pnl_margin | `live_scorecard_api` | `daily_midnight_current_truth_snapshot` | yes |
| `scorecard_amazon` | amazon_scorecard | `live_scorecard_api` | `daily_midnight_current_truth_snapshot` | yes |
| `scorecard_cash_pulse` | cash_pulse | `live_scorecard_api` | `daily_midnight_current_truth_snapshot` | yes |
| `scorecard_kpi_status` | scorecard_kpi_status | `live_scorecard_api` | `daily_midnight_current_truth_snapshot` | yes |
| `scorecard_europe_drilldowns` | europe_scorecard_drilldowns | `live_scorecard_api` | `daily_midnight_current_truth_snapshot` | yes |
| `batch_release_app` | quality_and_batch_release | `live_batch_release_app_state` | `daily_midnight_current_truth_snapshot` | yes |
| `netsuite_account_catalog` | finance_and_operations | `live_netsuite_account_catalog_audit` | `daily_midnight_current_truth_audit_snapshot` | yes |
| `netsuite_items` | finance_and_operations | `live_netsuite_suiteql` | `daily_midnight_current_truth_snapshot` | yes |
| `netsuite_pnl_monthly` | finance_and_operations | `live_netsuite_suiteql` | `daily_midnight_current_truth_snapshot` | yes |
| `netsuite_ar_open_invoices` | finance_and_operations | `live_netsuite_suiteql` | `daily_midnight_current_truth_snapshot` | yes |
| `netsuite_ap_open_bills` | finance_and_operations | `live_netsuite_suiteql` | `daily_midnight_current_truth_snapshot` | yes |
| `netsuite_inventory_snapshot` | finance_and_operations | `live_netsuite_suiteql` | `daily_midnight_current_truth_snapshot` | yes |
| `netsuite_revenue_by_sku_ytd` | finance_and_sales | `live_netsuite_suiteql` | `daily_midnight_current_truth_snapshot` | yes |
| `netsuite_revenue_by_customer_sku_channel_ytd` | finance_and_sales | `live_netsuite_suiteql` | `daily_midnight_current_truth_snapshot` | yes |

The Quality/R&D SharePoint document-library lanes are fully source for their
declared folder boundaries. As of the 2026-05-09 hosted Graph refresh, Quality
Vault finalized SOPs has 9 folders, 65 files, and 886 atomic rows; R&D
ProcessDev EGB SOPs has 1 folder, 11 files, and 72 atomic rows. As of the
2026-05-10 hosted Graph refresh, R&D ProcessDev Project OneStream has 67
folders, 92 files, and 13,936 atomic rows.

The JUST Phase 3b proposal lane is fully source for the delivered PDF snapshot
as of the 2026-05-09 hosted parse: 1 source file, 7 PDF text chunks, and 8
atomic rows. It is proposal evidence only, not approval or current operational
truth by itself.

The R&D Formulations Vault production-formula lane is canonical for
production-related formula questions inside the Formulations-Vault SharePoint
library. As of the 2026-05-10 hosted Graph refresh, it has 109 folders, 166
files, and 12,331 atomic rows.

Current Braintrust receipt:

- Project: `Andes / ask-just`
- Project id: `2a580ddb-dbad-4acd-a8b7-eacc2ab91123`
- Query responses include `trace_id`, `trace_span_id`, `trace_project`, `trace_project_id`, and `trace_url` when `BRAINTRUST_API_KEY` is configured and callers request trace metadata.
- Query traces include spans for `trace.user_question`, `trace.tool_call.1.ask_just_source_query`, `trace.selected_evidence`, `trace.source_receipts`, and `trace.final_answer`.

The active SQLite default is
`artifacts/ask-just-fresh-source-plane/source_index.sqlite`.

## How To Ask

In Codex, use the repo-owned skill:

```text
what was February revenue? [$askjust](/Users/josh/.codex/skills/askjust/SKILL.md)
```

The user should not need to know which source, database, table, source id, or
CLI flag contains the answer. `$askjust` means: ask Just's verified source
plane, choose the right source lane, answer with evidence, and say clearly when
the local memory does not yet contain enough evidence.

For direct shell use, the `ask-just` CLI calls the hosted Ask Just service.

Install or refresh the CLI from the hosted Ask Just service:

```bash
ASK_JUST_INSTALLER="$(mktemp -t ask-just-install.XXXXXX)"
curl -fsSL https://ask-just.35.222.146.245.sslip.io/install.sh -o "$ASK_JUST_INSTALLER"
bash -n "$ASK_JUST_INSTALLER"
bash "$ASK_JUST_INSTALLER"
rm -f "$ASK_JUST_INSTALLER"
```

If an admin needs to create a one-time setup code for a teammate:

```bash
ask-just onboarding-code create --label "Pri setup" --ttl-hours 24
```

For the employee parity experience, reset the previous Ask Just install, run
quietly, exchange the one-time setup code for the real token, and let the
installer run `ask-just doctor`:

```bash
ASK_JUST_INSTALLER="$(mktemp -t ask-just-install.XXXXXX)"
curl -fsSL https://ask-just.35.222.146.245.sslip.io/install.sh -o "$ASK_JUST_INSTALLER"
bash -n "$ASK_JUST_INSTALLER"
ASK_JUST_SETUP_CODE='<paste-setup-code-here>' ASK_JUST_RESET=1 ASK_JUST_QUIET=1 bash "$ASK_JUST_INSTALLER"
rm -f "$ASK_JUST_INSTALLER"
```

The file-first shape keeps the installer reviewable and avoids agent policies
that block streamed remote shell execution.

The hosted installer downloads the CLI to `~/.local/bin/ask-just`, refreshes
the Ask Just Codex skills under `~/.codex/skills/` (`askjust`, `just-source`,
`correction`, and `braintrust`), configures the token from
`ASK_JUST_SETUP_CODE` or `ASK_JUST_TOKEN`, enables those skills in the global
Codex skill config so new threads in any project can see them, runs
`ask-just doctor`, and writes a managed global `~/.codex/AGENTS.md` rule so
plain Just questions route through Ask Just instead of web search unless the
user explicitly asks for web/public lookup. It keeps GitHub out of the normal
employee setup path.
`ASK_JUST_RESET=1` removes only the previous Ask Just CLI, local Ask Just
config, and these four Ask Just skills before reinstalling. If the hosted
installer is temporarily unavailable, the
installer can still fall back to an authenticated GitHub CLI or
`GITHUB_TOKEN`/`GH_TOKEN` with read access to `manintheandes/ask-just`.

On success, the installer prints the welcome message and stops:

```text
Ask Just is how you have a conversation with the company.
```

For manual employee setup parity checks, run the local doctor after install:

```bash
export PATH="$HOME/.local/bin:$PATH"
ask-just doctor
```

The doctor checks the installed `ask-just` binary, PATH, local config, hosted
readiness, hosted source inventory, and Codex skills (`askjust`, `just-source`,
`correction`, and `braintrust`) without printing the bearer token. It returns
`ok: true`, `status: ready`, and an empty `required_gaps` list only when the
standard Ask Just setup is ready.

Do not use NetSuite, SQL, revenue, transactions, items, or any other business
source as part of employee setup verification.

Then ask source-backed questions:

```bash
export PATH="$HOME/.local/bin:$PATH"
ask-just doctor
ask-just health --deep
ask-just summary
ask-just sources
ask-just answer "what was our revenue last month"
ask-just --include-trace query "Mar gross revenue" --source scorecard_monthly_data --kind atomic --limit 3
ask-just query "WALMART CORP RMA IMPOSSIBLE dollars" --source spins_plant_based_meat_powertabs --kind atomic --limit 6
ask-just query "Protein on Hold mar" --source scorecard_ops_metrics --kind atomic --limit 3
ask-just query "scorecard velocity by SKU and retailer" --source scorecard_retail_velocity --kind atomic --limit 5
ask-just query "held batches" --source batch_release_app --kind atomic --limit 6
ask-just personal-mail-status
ask-just personal-mail-search "Publix" --days 30 --limit 10
ask-just query "customrecord outlook sync part tracker" --source netsuite_account_catalog --kind atomic --limit 5
ask-just query "Mung Bean" --source netsuite_items --kind atomic --limit 8
ask-just query "March 2026 net revenue" --source netsuite_pnl_monthly --kind atomic --limit 5
ask-just query "open AR invoices" --source netsuite_ar_open_invoices --kind atomic --limit 5
ask-just query "open AP bills" --source netsuite_ap_open_bills --kind atomic --limit 5
ask-just query "inventory on hand" --source netsuite_inventory_snapshot --kind atomic --limit 5
ask-just sql "select received_date, primary_intent, subject from wecare_customer_issue_summaries where is_refund_request = 1 order by received_date_time desc limit 5"
ask-just sql "select count(*) as n from atomic_rows"
```

For normal teammate use, `ask-just answer` is the locked question surface.
`ask-just query`, `ask-just search`, and `ask-just sql` are diagnostic or
power-user tools for source debugging, not something a teammate should have to
choose when asking a business question. Agent runtimes that can emit full-turn
events should write a JSON/JSONL event log and set
`ASK_JUST_NORMAL_ANSWER_AGENT_EVENTS` before calling `ask-just answer`; the
command will fail before querying if that turn contains speculative status text,
forbidden tools, rewritten questions, or hidden routing hints. The same check is
available directly with
`ask-just normal-answer-guard --question "QUESTION" --events EVENTS.jsonl`.

Fresh source lanes:

```bash
python3 scripts/build_strict_source_completion_table.py
python3 scripts/build_source_required_inputs.py
python3 scripts/check_vm_source_refresh_status.py
python3 scripts/verify_source_goal_complete.py
ask-just health --deep
ask-just query "Mar gross revenue" --source scorecard_monthly_data --kind atomic --limit 3
ask-just query "PUBLIX CORP RMA JUST Egg Plant Based Scramble 16 Oz 4.2" --source spins_breakfast_powertabs --kind atomic --limit 1
```

The WECARE mailbox lane refreshes daily from Microsoft Graph over the rolling
last 30 days for `wecare@ju.st` across inbox, archive, sent items, deleted
items, and junk. It writes message rows, attachment metadata, mailbox metrics,
and typed `wecare_customer_issue_summaries` rows for refund, spoilage, shipping,
contact-form, product complaint, product-term, retailer, and sender-domain
queries.

The CLI returns JSON so Codex, Claude Code, shell scripts, and future dashboards
can consume the same source evidence reliably.

## How Corrections Improve Ask Just

When Ask Just gives a weak answer, the fix should become part of the system, not
just part of one chat. There are three places to make that correction.

### 1. Fix the agent instructions

Update the `$askjust` skill when Codex or Claude misunderstood the question or
chose the wrong source.

Example: if someone asks for current KPIs, the skill should route to Scorecard
current truth through hosted Ask Just or say the hosted source index only has
routing/proof records, instead of treating narrative context as exact current
metrics.

### 2. Fix the shared rulebook

Update the README or spec when the rule should be visible to everyone working on
Ask Just.

Example: velocity should use Scorecard first whenever Scorecard contains the
requested retailer, SKU/product, period, grain, and velocity metric. SPINS, HEB,
and Whole Foods lanes are upstream or retailer-specific fallbacks only for
grains Scorecard does not display, or when the user explicitly asks for that
source's mechanics. The spec should name the exact boundary and require it to
be rebuilt into SQLite so future agents do not fall back to the retailer review
calendar/reset tracker, stale upstream snapshots, or generic context. The
`target_tracker` source id is a workbook for retailer review calendars and
resets; it is not Target customer evidence.

Normal business-answer mode requires a canonical owner before answering. If no
canonical owner manifest, structured source card, or trusted hosted planner
route claims the requested fact type, Ask Just returns `canonical_owner_gap` and
does not use broad text search, rival lanes, raw files, SQL spelunking, web
search, or memory to rescue the answer.

For production planner questions, route to
`operations_production_plan_latest`: production plan, production planner,
forecasted demand, fill order, run plan, upstream demand, capacity, inventory,
and production schedule. Do not use `target_tracker` as supporting evidence for
production planner answers; it is only for retailer review timelines, reset
timing, buyer review, submission status, accepted/declined status, and retailer
calendar context unless explicitly requested.
For customer forecast questions, query the production plan `2026 Forecast`
rows for the named customer and product family first; broaden within
`operations_production_plan_latest` only if exact customer rows are missing.

For SPINS velocity, the first answer path is the structured visible PowerTabs
`Item` / Item Ranking report table, `spins_item_ranking_rows`. Decoded
`pivot_cache_records` are supporting or fallback evidence; a pivot-cache miss is
not a source miss when the visible report row exists.

SPINS Item Ranking answers are contract-gated. The finish gate is:

```bash
python3 scripts/run_askjust_spins_item_ranking_soak.py
```

The gate checks that Item Ranking questions use typed `spins_item_rankings`
rows, not FTS snippets, and that route, slice, metric, provenance, fail-closed
behavior, and latency stay correct.

When reproducing a PowerTabs report manually, the stable path is: open the
right workbook, go to `Item`, use `Geo` as the retailer/geography selector,
choose the time period, then choose the category and subcategory that match the
SKU family. For breakfast, JUST Egg liquid is `REFRIGERATED EGGS` /
`RF EGGS LIQUID`; JUST Egg Folded and burritos are in
`FROZEN BREAKFAST FOODS` with the matching frozen breakfast subcategory. An
incompatible category/subcategory slicer state can hide valid rows and must be
cleared or corrected before treating the result as a source gap.

The durable SPINS target is a standard all-period Item Ranking slice layer, not
an ad hoc currently-open Excel view. It is the upstream/source-specific retail
analytics layer, while displayed Scorecard retail velocity remains canonical
through `scorecard_retail_velocity`. For each relevant SPINS workbook,
materialize `4 Weeks`, `12 Weeks`, `24 Weeks`, and `52 Weeks` Item Ranking rows
for `MULO`, `NATURAL`, and every retailer/geography listed in SPINS. Preserve
every visible SKU row, including competitors, across the frozen breakfast,
refrigerated eggs, meat, protein powder, and condiment workbooks. Unit velocity
is `Average Weekly Units Per Store Selling Per Item`; dollar velocity or
dollars per door per week is `Average Weekly Dollars Per Store Selling Per
Item`. If the user does not specify a period, answer velocity from `4 Weeks` by
default.

The global SPINS coverage gate is SKU x slicer based. Generate the coverage
matrix with:

```bash
python3 scripts/build_spins_item_ranking_coverage.py
```

The matrix records every JUST SKU found in SPINS Item Ranking rows, every
available source/channel/geography/period/category/subcategory slice, metric
availability, workbook Rank-column availability, and provenance samples.
Explicit SPINS/source-specific questions must answer from the exact typed SPINS
slice or return a stable source gap such as `missing_spins_sku_slice`,
`missing_spins_measure`, `missing_spins_slicer_universe`, or
`missing_workbook_rank_column`.

Workbook-native slicers define the answer universe. A full-channel ranking is
`Geography = (All)` plus `Channel = MULO`, `NATURAL`, or `(All)` when both
channels are selected. A retailer ranking is a specific Geography/Retail
Account. Every SPINS rank, velocity, dollar, category, channel, retailer, or
geography answer must report the slicer universe first: Geography, Channel,
Time Period, Category, Subcategory, Brand, and Measure. The returned `rank`
must be the workbook `Rank` column. If that workbook-native rank is absent,
Ask Just must return a source gap instead of calculating rank.

If Excel is showing a recovered or newly filtered PowerTabs state, capture that
visible report before rebuilding:

```bash
python3 scripts/capture_spins_visible_item_ranking.py --source-id spins_breakfast_powertabs
python3 scripts/build_fresh_source_database.py --source-id spins_breakfast_powertabs
```

The capture writes `*.visible-item-ranking.json` under
`source-material/<source-id>/visible-item-ranking-snapshots/`, and the builder
ingests every captured view into `spins_item_ranking_rows` with Excel-visible
report provenance.

### 3. Fix the tool

Add or improve a CLI/API command when the same question will come up again and
should not depend on a fresh ad hoc SQL query each time.

Example: if revenue or velocity questions become common, add named commands that
always use the right source id, table, filters, and provenance rules.

For most Just teammates, the workflow stays simple: ask through Codex, Claude,
or another agent and inspect the evidence. Power users can also use the local
CLI directly. Everyone benefits when recurring corrections are captured in
these shared layers.

## Hosted Service

Ask Just now has a small shared VM host, and the same service can still run locally for development.

| Piece | Value |
| --- | --- |
| GCP project | `ask-just-prod` |
| VM | `ask-just-server` in `us-central1-a` |
| VM repo | `/home/josh/ask-just` |
| Local repo | `/Users/josh/projects/ask-just` |
| Private VM service | `http://127.0.0.1:8792` |
| Public HTTPS endpoint | `https://ask-just.35.222.146.245.sslip.io` |
| SQLite index | `artifacts/ask-just-fresh-source-plane/source_index.sqlite` |
| Builder | `scripts/build_fresh_source_database.py` |
| CLI client | `ask-just` / `scripts/ask_just.py` |
| Service unit | `deploy/systemd/ask-just.service` |
| Daily refresh units | `deploy/systemd/ask-just-source-refresh.service` / `deploy/systemd/ask-just-source-refresh.timer` |

The Python service is read-only and bound to localhost on the VM. Public traffic
enters through HTTPS and bearer-token auth, then nginx proxies to the private
localhost service.

The SQLite index lives at:

```text
/home/josh/ask-just/artifacts/ask-just-fresh-source-plane/source_index.sqlite
```

That database is the answer-data artifact. It is generated runtime state, so the
durable repo assets are the maps, parser code, receipts, and tests that rebuild
and verify it. Promote staged rebuilds to the VM only after health, count, gap,
hash, and query checks pass.

Build the SQLite index:

```bash
python3 scripts/build_fresh_source_database.py
```

Run the local HTTP server:

```bash
python3 scripts/serve_http.py --host 127.0.0.1 --port 8792
```

Install or refresh the VM service:

```bash
sudo install -m 0644 deploy/systemd/ask-just.service /etc/systemd/system/ask-just.service
sudo systemctl daemon-reload
sudo systemctl enable --now ask-just.service
```

Install or refresh the VM daily source-refresh automation:

```bash
sudo install -d -m 0750 /etc/ask-just
sudo install -m 0600 deploy/systemd/source-refresh.env.example /etc/ask-just/source-refresh.env
sudoedit /etc/ask-just/source-refresh.env
sudo install -m 0644 deploy/systemd/ask-just-source-refresh.service /etc/systemd/system/ask-just-source-refresh.service
sudo install -m 0644 deploy/systemd/ask-just-source-refresh.timer /etc/systemd/system/ask-just-source-refresh.timer
sudo systemctl daemon-reload
sudo systemctl start ask-just-source-refresh.service
sudo systemctl enable --now ask-just-source-refresh.timer
systemctl list-timers ask-just-source-refresh.timer
python3 scripts/check_vm_source_refresh_status.py --transport gcloud
```

The timer runs daily at midnight America/Los_Angeles on the VM through
`scripts/refresh_source_lanes.py`, which rebuilds the source index and writes
`source_lane_refresh_report.json`. The hosted checkout guard also repairs and
reenables the checked-in source-refresh timer when systemd drift is detected.
`scripts/check_vm_source_refresh_status.py` fails if the timer is missing,
disabled, pointed at the wrong script, stale, `finalize_only`, or incomplete.
Non-SPINS lanes use Graph
delta, source API cursors, HTTP validators, modified time, or hash-delta as
appropriate. The WECARE mailbox lane refreshes daily from Microsoft Graph over
the rolling last 30 days for `wecare@ju.st` across inbound customer-signal
folders. It intentionally does not source sent replies, junk, WECARE-authored
mail, admin notifications, vendor pitches, conference/hotel spam, or other
non-customer mailbox noise. Its typed table `wecare_customer_issue_summaries`
tags refund, spoilage, shipping, contact-form, product complaint, product-term,
retailer, and sender-domain fields for customer-signal CX questions. Asana is a key
work-management source lane: it requires token-backed active and archived
project enumeration for catalog facts, plus rolling 30-day task activity for
selected source teams and explicit source projects. Rolling modified-task rows
are current work-item evidence, while project catalog rows remain the source for
old named project existence/owner/team/link questions. SPINS lanes remain delivered
workbook snapshots until a new workbook delivery is persisted under
`source-material/`.

`/etc/ask-just/source-refresh.env` must contain one supported Microsoft Graph
credential shape for Graph-backed lanes: `MS_TENANT_ID`,
`MS_GRAPH_CLIENT_ID`, and `MS_GRAPH_CLIENT_SECRET`; the previous
order-allocation `GRAPH_TENANT_ID`, `GRAPH_CLIENT_ID`, and
`GRAPH_CLIENT_SECRET` shape; or delegated `GRAPH_TENANT_ID`,
`GRAPH_CLIENT_ID`, and `GRAPH_REFRESH_TOKEN`. Do not mark the source goal
complete unless `python3 scripts/verify_source_goal_complete.py` is green after
the VM refresh service succeeds and any source-specific manifest closure audits
are green.

## Personal Source Overlay

Ask Just can let one bearer token unlock both the shared company source plane
and that user's private Microsoft Graph mailbox. This is intentionally not a
shared source lane: personal mailbox rows are queried live through delegated
Graph access and are not written into the shared SQLite index.

The server reads an optional registry from `ASK_JUST_PERSONAL_SOURCES`, usually
`/etc/ask-just/personal-sources.json`. Each registry entry maps a SHA-256 hash
of a user's Ask Just bearer token to that user's mailbox and env-var names for
delegated Graph credentials. Use
`deploy/systemd/personal-sources.example.json` and
`deploy/systemd/http.env.example` as the install templates.

To compute the registry hash for the current configured Ask Just token:

```bash
ask-just token-hash
```

Personal mailbox commands:

```bash
ask-just personal-mail-status
ask-just personal-mail-search "Lisa Publix" --days 30 --limit 10
ask-just personal-mail-read "<message-id>"
ask-just personal-mail-draft --to "person@example.com" --subject "Subject" --body "Draft body"
ask-just personal-mail-reply-draft "<message-id>" --body "Reply draft body"
ask-just personal-mail-send-draft "<draft-message-id>"
```

Privacy rule: company sources are shared; personal sources inherit the ACL of
the token owner and are visible only to that mapped bearer token. Actual
delivery is intentionally a separate `personal-mail-send-draft` command; normal
write operations create drafts.

Health check:

```bash
ask-just health --deep
```

Source-specific hosted proof:

```bash
ask-just query "Protein on Hold mar" --source scorecard_ops_metrics --kind atomic --limit 3
ask-just query "held batches" --source batch_release_app --kind atomic --limit 6
ask-just query "customrecord outlook sync part tracker" --source netsuite_account_catalog --kind atomic --limit 5
ask-just query "Mung Bean" --source netsuite_items --kind atomic --limit 8
```

The VM service and laptop tunnel were verified on 2026-05-02 for
`scorecard_ops_metrics`: `Protein on Hold mar` returns field-level provenance
for `Upstream Inventory:Protein on Hold (MT):mar` with value `46`.
The local Batch Release ask surface was verified on 2026-05-03:
`held batches` returns field-level provenance for Batch Release records, with
6 held status rows in the current app-state read-data snapshot.
The NetSuite account catalog audit lane was verified on 2026-05-04:
`vendorBill suiteql row count` returns `netsuite_record_type_catalog`, and
`customrecord outlook sync part tracker` returns
`netsuite_metadata_catalog_root_items` from the root metadata catalog.
The VM NetSuite item source was verified on 2026-05-02: the VM rebuilt from
live SuiteQL using its private `NETSUITE_*` environment file, and `Mung Bean`
returns field-level provenance from `netsuite:/suiteql/item`.

See [docs/local-http-service.md](docs/local-http-service.md) and
[docs/remote-cli.md](docs/remote-cli.md).

## Codex Skills

This repo owns the Codex skills that make the experience feel like asking the
company rather than running a database query:

```text
skills/askjust/SKILL.md
skills/braintrust/SKILL.md
skills/correction/SKILL.md
skills/just-source/SKILL.md
```

`just-source` defines when a Just artifact becomes source-grade. `$askjust` is
the conversational front door over source-grade Just memory. `correction`
defines what to do when an Ask Just answer needs a durable routing or answer
fix. `braintrust` defines the Ask Just trace inspection and verification
workflow.

## Source Links

Ask Just answers still come from the hosted API backed by the verified GCP VM
SQLite source index. Source links are an inspection layer over that evidence:
rows with `provenance_grain` are enriched with `source_links`, and the same
resolver is available directly:

```bash
ask-just source-links --source-id spins_plant_based_meat_powertabs \
  --locator "/Users/josh/Downloads/SPINS PowerTabs Eat Just Plant Based Meat Data Ending 04-19-26 (1).xlsb#sheet=Retailer&row=16"
```

The resolver uses hosted source-index tables such as `atomic_rows`,
`source_files`, and source provenance to return the upstream artifact handle:
local workbook paths, HTTP/API URLs, or structured locators such as
`netsuite:/suiteql/...`. Links are for source inspection and trust; they do not
replace the hosted API as the normal answer path.

Verify link coverage for the currently built SQLite plane with:

```bash
python3 scripts/audit_source_links.py
```

## Braintrust Tracing

Ask Just query requests emit Braintrust traces when the runtime has the Python
dependency and an API key:

```bash
python3 -m venv .venv
. .venv/bin/activate
python3 -m pip install -r requirements.txt
export BRAINTRUST_API_KEY=...
export ASK_JUST_BRAINTRUST_PROJECT=ask-just
export ASK_JUST_BRAINTRUST_PROJECT_ID=2a580ddb-dbad-4acd-a8b7-eacc2ab91123
```

Tracing fails open: if the SDK or API key is missing, source queries still run
and simply omit trace fields. The CLI does not trace ordinary calls, so source
answers stay fast and provenance is not mixed with observability metadata. Use
`--include-trace` or `--open-trace` when debugging a run. The local Braintrust
context is stored in `.bt/config.json`.

Runtime tracing is non-blocking by default so CLI answers are not delayed by
Braintrust network flushes. For a debugging session that must wait until trace
events are uploaded, set `ASK_JUST_BRAINTRUST_SYNC_FLUSH=1`. To force tracing
for every hosted request, set `ASK_JUST_BRAINTRUST_TRACE_ALL=1`.

The source capability registry is a classification and audit contract, not a
runtime planner. Queryable means a source has atomic rows or live-query proof.
Computable means a named capability declares the dimensions, measures,
operators, grain, and provenance needed for that calculation. Run:

```bash
python3 scripts/audit_source_capabilities.py --json
```

That default audit proves schema and source-inventory coverage. Add
`--source-map config/fresh-source-map.yaml --receipts-root receipts/fresh` when
you intentionally want the audit to prove local source-map and receipt files
too; those flags should fail if that proof is missing.

## Source Plane

- Source plane id: `ask_just_fresh_source_plane`
- Active source map: [config/fresh-source-map.yaml](config/fresh-source-map.yaml)
- Source capability registry:
  [config/source-capabilities.yaml](config/source-capabilities.yaml)
- Parser: `scripts/build_fresh_source_database.py`
- Query helper: `ask-just`
- Local rebuild index: `artifacts/ask-just-fresh-source-plane/source_index.sqlite`
- VM index: `/home/josh/ask-just/artifacts/ask-just-fresh-source-plane/source_index.sqlite`
- Receipts: `receipts/fresh/`

## Repo Layout

```text
config/fresh-source-map.yaml                   Active fresh Ask Just source-lane map
config/source-map.yaml                         Active wrapper map for the fresh source plane
config/queryable-source-ids.json               Canonical queryable source ids
config/source-capabilities.yaml                Source answerability and capability registry
config/child-source-registry.json              Promoted manifest child source ids
config/semantic-child-source-registry.json     Semantic child source ids inside larger lanes
receipts/fresh/                                Machine-readable receipts for active lanes
docs/source-receipts/                          Human-readable receipt summaries
artifacts/ask-just-fresh-source-plane/         Generated local rebuild artifacts
scripts/build_fresh_source_database.py         Fresh source-index builder
scripts/audit_source_capabilities.py           Source capability registry audit
scripts/serve_http.py                          Read-only local HTTP API
scripts/ask_just.py                            CLI client
install.sh                                     One-line installer for ~/.local/bin/ask-just
skills/askjust/SKILL.md                        Codex routing skill
```
