ask-just 0.1.8

Thin CLI for the hosted Ask Just source plane

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:

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:

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 for the deeper product contract and future direction. Read docs/ask-just-model-card.md for the model card and docs/ask-just-release-notes.md for release history. Read 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 for the phase audit behind the current source-plane claim. Read 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.

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.

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

Use these visuals to explain product boundaries like:

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:

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:

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:

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 [e-mail] plus Inventory Stock Summary Report; Bethlehem defaults to [e-mail] 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 source-capability registry foundation, Ask Just declares 112 source lanes in config/all-source-ids.json; 108 are intended for the Ask surface in config/queryable-source-ids.json. tofutown_qvd_last_90_days, tofutown_production_planning_folder, teams_daily_product_sync, and operations_order_allocation 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 waits on source-grade hosted TofuTown folder refresh proof before it can return to the Ask surface. 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:

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
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
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:

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 -c 'curl -fsSL https://ask-just.35.222.146.245.sslip.io/install.sh | bash'

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

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:

ASK_JUST_SETUP_CODE='<paste-setup-code-here>' ASK_JUST_RESET=1 ASK_JUST_QUIET=1 bash -c 'curl -fsSL https://ask-just.35.222.146.245.sslip.io/install.sh | bash'

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:

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

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

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:

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:

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 [e-mail] 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 SPINS last 4 weeks by default, with HEB and Whole Foods as explicit retailer-specific exceptions. 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 Scorecard, or generic context. The target_tracker source id is a workbook for retailer review calendars and resets; it is not Target customer evidence.

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:

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. 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:

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. Ask Just 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:

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:

/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:

python3 scripts/build_fresh_source_database.py

Run the local HTTP server:

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

Install or refresh the VM service:

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:

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 [e-mail] 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:

ask-just token-hash

Personal mailbox commands:

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 "[e-mail]" --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:

ask-just health --deep

Source-specific hosted proof:

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 and 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:

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:

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:

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:

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:

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
• Source capability registry: 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

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